Skip to content

API spec

The latest OpenAPI document is public/swagger/swagger.json in the frontend repository (OpenAPI 3.0.0, title Verilib API, version 1.0.0), served by public/swagger/index.html. The development environment exposes the live Swagger UI. It reflects the current /v2 endpoint implementations and defines the JSON surface listed below. Cookie session auth (withCredentials: true) is used by the web client unless an endpoint also accepts an API key.

Authentication

  • Bearer session: Authorization: Bearer <token>.
  • API key: Authorization: ApiKey <token> for CLI-facing upload and repository operations.
  • A security array containing both schemes means either credential type may be used.
  • Endpoints without a security declaration are publicly readable.

/v2 endpoint inventory

Account

Method Path Purpose
GET /v2/user/job-notifications Background upload/atomize notifications for repos the user owns or can edit. See Job notifications.
GET /v2/account/keys List active API keys.
POST /v2/account/keys Create an API key with ALL, reclone, or json-only permissions and optional expiry.
DELETE /v2/account/keys/{id} Revoke an API key.
PUT /v2/account/setting Update supported account settings.

Atoms and bounty

Method Path Purpose
GET / PUT /v2/atoms/{atom_id}/issues List or associate GitHub issues.
DELETE /v2/atoms/{atom_id}/issues/{issue_id} Remove a GitHub issue association.
GET /v2/atoms/{atom_id}/children Return descendant atoms and dependency metadata.
PUT /v2/atoms/labels Add or remove a label from multiple atoms.
PUT /v2/atoms/bookmark/{atom_id} Toggle an atom bookmark.
POST /v2/bounty/{atom_id}/attempt Record a bounty attempt.
POST /v2/bounty/{atom_id}/submit_bounty Submit a bounty attempt and proof.
POST /v2/bounty/{atom_id}/submit_proof Store proof text for a bounty attempt.

Code map and catalogs

Method Path Purpose
GET /v2/code_map/ids Return configured code-map identifiers.
GET /v2/languages List supported programming languages.
GET /v2/types List repository and application types.
GET /v2/verifier/versions/{language_id} List verifier versions for a language.

Repository operations

Method Path Purpose
POST /v2/repo/create Create a repository and start upload processing.
POST /v2/json-only/repo/create Create a repository for a JSON-only workflow.
POST /v2/repo/deploy Create or redeploy a repository tree.
POST /v2/json-only/repo/{repo_id}/atomize Import probe JSON for an existing repository.
GET /v2/repo/download/{repo_id} Export repository atoms, snippets, dependencies, and layouts.
GET /v2/repo/export/{repo_id} Export repository data.
GET /v2/repo/import/{repo_id} Import repository data.
GET /v2/repo/tree/{repo_id} Return the repository atom tree.
GET /v2/repo/{repo_id}/status Return repository verification counts.
GET /v2/repo/logs/{repo_id} Return upload logs and queue status.
GET /v2/repo/{id}/edit_info Return edit access and processing metadata.
GET /v2/repo/info/{id} Return repository metadata and atom data.
GET /v2/repo/note/{id} Return processing notes and status.
POST /v2/repo/{id}/update Update repository metadata and source settings.
POST /v2/repo/{id}/color-rules Validate and save repository color rules.
POST /v2/repo/publish/{repo_id} Publish a repository.
POST /v2/repo/unpublish/{repo_id} Unpublish a repository.
POST /v2/repo/reatomize/{repo_id} Queue a repository for atomization again.
POST /v2/repo/reclone/{repo_id} Queue a repository for recloning.
POST /v2/repo/rate/{id} Create or update the authenticated user's rating.
GET /v2/repo/resolve/id/{id} Resolve an ID to repository identity.
GET /v2/repo/resolve/{username}/{slug} Resolve an owner and slug to repository identity.
GET /v2/repo/shake_results/{repo_id} Process post-atomization results.

Repository labels and GitHub

Method Path Purpose
GET / POST /v2/repo/{repo_id}/labels List or create repository labels.
POST /v2/repo/github/check-url Check GitHub visibility and pending-user authorization.
POST /v2/repo/{id}/github/check-url Check and persist GitHub authorization for an existing repository.
POST /v2/repo/github/detect Detect repository language and proof language.
GET /v2/repo/github/auth-url Create an upload-flow GitHub authorization URL.
GET /v2/repo/{id}/github/auth-url Create a repository-specific GitHub authorization URL.
GET /v2/repo/{id}/github/folders List folders from an existing GitHub tree.
GET /v2/repo/github/pending-auth Report pending GitHub authorization state.

Path parameters named id, repo_id, atom_id, and language_id are required. Request and response field types, required fields, enums, operation IDs, and component schemas are defined by the checked-in Swagger document.

Classic / non-/v2 routes (selected)

Routed from public/web_routes.php:

Route Role
GET jobs Background jobs table (/jobs); requires auth. See Job notifications.
POST repobrowser/certify Create certificate snapshot; enqueue validate worker; leave certificates.status=pending
GET certificates Certificate UI / listing for a parent repo
Atomize helpers Legacy/internal atomize paths; JSON-only atomize documented in upstream docs/json-only-server-setup.md
Auth user API Under /api/user/ (used by scripts / auth wiring)

Queue side effects (not HTTP responses)

User action Downstream
Upload / reclone (when queue workers enabled) upload.request → atomizer
Certify Validate publish → certificates / cert queue
CLI traffic RabbitMQ CLI_* exchange/queue names from .env

This page is a readable inventory of the latest implementation-backed Swagger contract. The OpenAPI document is authoritative for endpoint paths, authentication, fields, response shapes, operation IDs, and component schemas.