Reference
HTTP API overview
The CI API under /v1, the Argos-compatible /v2, the dashboard's JSON API, webhooks and health endpoints.
CirCI's server answers on seven groups of paths. Scripts should use only the CI API (/v1) and the Argos-compatible API (/v2); webhooks are for git hosts and other tools sending events to CirCI.
| Prefix | For | Authentication |
|---|---|---|
/v1 |
The CI API: what circi upload uses. |
Authorization: Bearer circi_… (a project CI token). |
/v2 |
The Argos-compatible upload protocol. | The same token. |
/api |
The dashboard's JSON API. | The session cookie; changes need a same-origin request. Not a stable public API. |
/api/auth/* |
Sign-in and sessions (better-auth). | Public: you sign in here. |
/webhooks/:kind, /api/integrations/:kind/webhook |
Incoming webhooks of git hosts and other integrations. | Each provider's own signature. |
/healthz, /readyz, /api/auth-methods |
Liveness, readiness, the sign-in methods on offer. | None. |
/internal/* |
Answers the reverse proxy only (Caddy's tls-ask). |
Never reachable from browsers. |
The CI API (/v1)
Section titled “The CI API (/v1)”A token can only act on its own project. A session can't upload, and a token can't read the dashboard API.
| Method and path | Purpose |
|---|---|
GET /v1/project |
The authenticated project. |
POST /v1/builds |
Create a build (or join the shard of an existing one) from the commit, branch, pull request, base branch, ancestry and the list of screenshot files (SHA-256, size, image/png). Answers 201 with the build and the upload instructions for the files the server doesn't have. |
PUT /v1/files/:sha256 |
Upload a file through the API (local-disk storage). With S3, the instruction is a presigned URL bound to the checksum instead. Body: image/png or application/octet-stream. Stored only if the bytes hash to :sha256. |
POST /v1/builds/:id/finalize |
Send the screenshot names, hashes and metadata of one shard (shardIndex for sharded builds). 409 with the missing files when any weren't uploaded or failed verification. Answers complete and the shard counts. |
GET /v1/builds/:id/status |
The build, counts, outcome, gate and errorMessage. ?gate=status or ?gate=exit-code to ask for a mode. |
POST /v1/sites |
Upload a site as a .tar.gz (the CLI does this). 404 when hosting isn't set up, 403 when it's off for the project. |
GET /v1/sites/served |
Which sites the project serves. |
Limits: a screenshot at most 25 MB, a build at most 10,000 screenshots, JSON bodies at most 16 MB, at most 2,000 ancestor commits, at most 1,000 shards. Build names match [A-Za-z0-9][A-Za-z0-9._-]{0,63}.
Errors are JSON, { "error": "…" }, with the usual status: 401 for a missing or wrong token (with www-authenticate: Bearer), 400 for a request that fails validation, 404, 409, 413, 415, and 422 when an uploaded file doesn't match its checksum.
The upload sequence
Section titled “The upload sequence”-
POST /v1/buildswith the commit, ancestry and file list. Files the server already has verified aren't asked for again. -
Upload each requested file (parallel, with retries).
-
POST /v1/builds/:id/finalizeper shard. The build starts processing when the last shard arrives. -
Poll
GET /v1/builds/:id/status(this is what--waitdoes) until the build is no longer processing.
This is an implementation detail of the CLI; prefer circi upload over writing your own client.
Other endpoints
Section titled “Other endpoints”- Webhooks out: a project's signed
build.completedandbuild.reviewedevents: Webhooks. - Health:
GET /healthzanswers{ "status": "ok" }while the process serves.GET /readyzalso checks the database and storage, each with a timeout so a hung dependency can't hang the probe. - Sign-in methods:
GET /api/auth-methods.
Every field, status code and retry rule of these endpoints is in the CI API reference; the messages and exit codes are in Errors and exit codes; sizes and counts in Limits.