This reference is generated from the server's OpenAPI contract. Rebuild it after changing API routes or operation summaries with:
cargo run -p circus-xtask -- api-docsAll versioned JSON endpoints live under /api/v1. GET, HEAD,
and OPTIONS requests are generally public unless a handler requires
a user or admin session. Mutating requests require
Authorization: Bearer <api-key> and may require a specific role.
| Method | Endpoint | Description | Responses |
|---|---|---|---|
| GET | /api/v1/admin/audit-log |
Paginated audit log (admin only) | 200 |
| GET | /api/v1/admin/builders |
List remote builders | 200 |
| POST | /api/v1/admin/builders |
Register a builder | 200 |
| GET | /api/v1/admin/builders/sessions |
List all persistent builder agent sessions (connected + historical) | 200 |
| GET | /api/v1/admin/builders/sessions/connected |
List currently-connected builder agents | 200 |
| GET | /api/v1/admin/builders/sessions/{machine_id} |
Get a single builder agent session by its stable machine_id | 200, 404 |
| GET | /api/v1/admin/builders/{id} |
Get a builder | 200 |
| PUT | /api/v1/admin/builders/{id} |
Update a builder | 200 |
| DELETE | /api/v1/admin/builders/{id} |
Remove a builder | 204 |
| GET | /api/v1/admin/config |
Read the server config file | 200 |
| PUT | /api/v1/admin/config |
Replace the server config file | 200 |
| GET | /api/v1/admin/notification-tasks |
List pending notification delivery tasks | 200 |
| POST | /api/v1/admin/notification-tasks/{id}/retry |
Retry a notification delivery task | 202 |
| GET | /api/v1/admin/pinned-build-products |
List build products protected by kept builds | 200 |
| POST | /api/v1/admin/pinned-builds/{id}/unpin |
Clear keep for a build and make its products GC-eligible | 200 |
| GET | /api/v1/admin/system |
System status | 200 |
| GET | /api/v1/api-keys |
List API keys | 200 |
| POST | /api/v1/api-keys |
Create an API key | 200 |
| DELETE | /api/v1/api-keys/{id} |
Revoke an API key | 204 |
| GET | /api/v1/auth/github |
Start GitHub OAuth login | 302 |
| GET | /api/v1/auth/github/callback |
Complete GitHub OAuth login | 302 |
| GET | /api/v1/builds |
List builds | 200 |
| GET | /api/v1/builds/recent |
Most recent builds | 200 |
| GET | /api/v1/builds/stats |
Build statistics | 200 |
| GET | /api/v1/builds/{build_id}/products/{product_id}/download |
Download a build product (binary stream) | 200 |
| GET | /api/v1/builds/{id} |
Get a build | 200 |
| POST | /api/v1/builds/{id}/bump |
Bump build priority | 200 |
| POST | /api/v1/builds/{id}/cancel |
Cancel a build | 200 |
| GET | /api/v1/builds/{id}/constituents |
List constituents of an aggregate build | 200, 422 |
| GET | /api/v1/builds/{id}/dependencies |
List builds this build depends on | 200 |
| GET | /api/v1/builds/{id}/dependents |
List builds that depend on this build | 200 |
| PUT | /api/v1/builds/{id}/keep/{value} |
Pin or unpin a build from GC | 200 |
| GET | /api/v1/builds/{id}/log |
Get build log (text) | 200 |
| GET | /api/v1/builds/{id}/log/stream |
SSE-stream the live build log | 200 |
| GET | /api/v1/builds/{id}/products |
List build products | 200 |
| POST | /api/v1/builds/{id}/restart |
Restart a build | 200 |
| GET | /api/v1/builds/{id}/steps |
List build steps | 200 |
| GET | /api/v1/channels |
List channels | 200 |
| POST | /api/v1/channels |
Create a channel | 200 |
| POST | /api/v1/channels/{channel_id}/promote/{eval_id} |
Promote an evaluation to a channel | 200 |
| GET | /api/v1/channels/{id} |
Get a channel | 200 |
| DELETE | /api/v1/channels/{id} |
Delete a channel | 204 |
| GET | /api/v1/channels/{id}/nixexprs.tar.xz |
Download channel nixexprs tarball | 200 |
| GET | /api/v1/evaluations |
List evaluations | 200 |
| POST | /api/v1/evaluations/trigger |
Trigger an evaluation | 202 |
| GET | /api/v1/evaluations/{id} |
Get an evaluation | 200 |
| GET | /api/v1/evaluations/{id}/compare |
Compare an evaluation against another | 200 |
| GET | /api/v1/me |
Get the current user | 200 |
| PUT | /api/v1/me |
Update the current user | 200 |
| POST | /api/v1/me/password |
Change the current user's password | 204 |
| GET | /api/v1/me/starred-jobs |
List starred jobs for the current user | 200 |
| POST | /api/v1/me/starred-jobs |
Star a job | 200 |
| DELETE | /api/v1/me/starred-jobs/{id} |
Unstar a job | 204 |
| GET | /api/v1/metrics/systems |
Build system distribution | 200 |
| GET | /api/v1/metrics/timeseries/builds |
Build count time series | 200 |
| GET | /api/v1/metrics/timeseries/duration |
Build duration percentile time series | 200 |
| GET | /api/v1/news |
List news/announcement entries | 200 |
| POST | /api/v1/news |
Create a news entry (admin only) | 201 |
| DELETE | /api/v1/news/{id} |
Delete a news entry (admin only) | 204 |
| GET | /api/v1/openapi.json |
OpenAPI specification | 200 |
| GET | /api/v1/projects |
List projects | 200 |
| POST | /api/v1/projects |
Create a project | 200 |
| POST | /api/v1/projects/probe |
Probe a repository URL for jobset hints | 200 |
| POST | /api/v1/projects/setup |
Create project + initial jobset in one call | 200 |
| GET | /api/v1/projects/{id} |
Get a project | 200, 404 |
| PUT | /api/v1/projects/{id} |
Update a project | 200 |
| DELETE | /api/v1/projects/{id} |
Delete a project | 204 |
| GET | /api/v1/projects/{id}/builds |
List builds for a project | 200 |
| GET | /api/v1/projects/{id}/jobsets |
List jobsets for a project | 200 |
| POST | /api/v1/projects/{id}/jobsets |
Create a jobset in a project | 200 |
| GET | /api/v1/projects/{id}/webhooks |
List configured webhooks | 200 |
| POST | /api/v1/projects/{id}/webhooks |
Register a webhook | 200 |
| DELETE | /api/v1/projects/{id}/webhooks/{webhook_id} |
Delete a webhook | 204 |
| GET | /api/v1/projects/{project_id}/channels |
List channels for a project | 200 |
| GET | /api/v1/projects/{project_id}/jobsets/{id} |
Get a jobset | 200 |
| PUT | /api/v1/projects/{project_id}/jobsets/{id} |
Update a jobset | 200 |
| DELETE | /api/v1/projects/{project_id}/jobsets/{id} |
Delete a jobset | 204 |
| GET | /api/v1/projects/{project_id}/jobsets/{jobset_id}/inputs |
List jobset inputs | 200 |
| POST | /api/v1/projects/{project_id}/jobsets/{jobset_id}/inputs |
Create a jobset input | 200 |
| DELETE | /api/v1/projects/{project_id}/jobsets/{jobset_id}/inputs/{input_id} |
Delete a jobset input | 204 |
| GET | /api/v1/search |
Advanced search | 200 |
| GET | /api/v1/search/quick |
Quick search (autocomplete) | 200 |
| GET | /api/v1/users |
List users | 200 |
| POST | /api/v1/users |
Create a user | 200 |
| GET | /api/v1/users/{id} |
Get a user | 200 |
| PUT | /api/v1/users/{id} |
Update a user | 200 |
| DELETE | /api/v1/users/{id} |
Delete a user | 204 |
| POST | /api/v1/webhooks/{project_id}/forgejo |
Forgejo webhook receiver | 200, 401 |
| POST | /api/v1/webhooks/{project_id}/gitea |
Gitea webhook receiver | 200, 401 |
| POST | /api/v1/webhooks/{project_id}/github |
GitHub webhook receiver | 200, 401 |
| POST | /api/v1/webhooks/{project_id}/gitlab |
GitLab webhook receiver | 200, 401 |
| POST | /auth/ldap |
Authenticate via LDAP bind (sets session cookie) | 200, 401 |
| GET | /channel/{name}/binary-cache-url |
Plain-text binary cache URL for this channel | 200 |
| GET | /channel/{name}/git-revision |
Plain-text git revision pinned to this channel | 200 |
| GET | /channel/{name}/nixexprs.tar.xz |
Hydra-compatible nixexprs tarball for this channel | 200 |
| GET | /channel/{name}/store-paths.xz |
xz-compressed list of channel store paths | 200 |
| GET | /health |
Health check with database and service status | 200, 503 |
| GET | /job/{project}/{jobset}/{job}/badge |
Build status badge SVG | 200 |
| GET | /job/{project}/{jobset}/{job}/latest |
Redirect to the latest successful build output | 302, 404 |
| GET | /job/{project}/{jobset}/{job}/shield |
Build status shield SVG | 200 |
| GET | /nix-cache/nar/{hash} |
NAR download | 200, 404 |
| GET | /nix-cache/nix-cache-info |
Nix binary cache metadata | 200 |
| GET | /nix-cache/{hash} |
NAR info lookup | 200, 404 |
| GET | /prometheus |
Prometheus metrics exposition | 200 |