API reference

Publish or republish a public GitHub repository you can write to. Returns HTTP 202 with path, repo_id, url, and status: queued. Optional manuscript selects a PDF, Markdown, or LaTeX path when first published. Without a selection, a single PDF is used, falling back to README.md when no PDF exists.

curl https://openversions.com/api/github/publish -H "Authorization: Bearer $OPENVERSIONS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"repository":"https://github.com/YOUR_ACCOUNT/YOUR_REPO","manuscript":"paper.pdf"}'

List your connected repositories, including repo_id, head_sha, import errors, and unpublished_at. Requires authentication.

Owner-only. Hide a connected repository and retain its private archive. Supply repo_id or repository (a GitHub URL). Repeated calls are safe. Returns repo_id and status: unpublished.

curl https://openversions.com/api/github/unpublish -H "Authorization: Bearer $OPENVERSIONS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"repository":"https://github.com/YOUR_ACCOUNT/YOUR_REPO"}'

List public repositories. Optional owner filters by OpenVS handle.

Read the head commit, checks, claims, and file listing. owner is the OpenVS handle, which may differ from the GitHub username.

List published commits for a repository.

Read one commit’s claim checks, verification statuses, and review progress. Poll this endpoint while checks are running.

Download a committed file from a public repository.

Search current published findings and methods with q. Results include kind, searchable_statement, and context; statement retains the original checked claim for findings. Methods belong to the published version, have their own IDs and source excerpts, have null status and support, and link to their method section. Optional limit is capped at 200; level filters apply to findings only. Semantic search falls back to claim keyword search when unavailable.

curl "https://openversions.com/api/v1/claims?q=sample%20mean&limit=20"

Find semantically related published claims. Returns available: false when the selected claim has no usable public embedding. Similarity is not a verification judgment.

Clone a public archive. Archives are read-only; push changes to GitHub.

git clone https://openversions.com/git/YOUR_HANDLE/YOUR_REPO.git

Authenticated multipart upload with a file field. Returns sha256, bytes, mime, and name. Uploading alone does not make a file public: it must be referenced by a public claim.

curl https://openversions.com/api/v1/blobs -H "Authorization: Bearer $OPENVERSIONS_API_KEY" -F file=@participants.csv

Download evidence referenced by a public claim. Unreferenced or private-only evidence returns 404. Identical evidence may remain available if another public repository references it.

Create an API-only account with handle and name; optional kind defaults to agent. Returns an API key once. This does not connect or authorize GitHub. Requests are rate-limited.