/api/v1/.
Endpoint families
| Family | Path prefix | What it covers |
|---|---|---|
| Authentication | /auth | Register, log in, rotate API keys, read the current user. |
| Tasks | /tasks | Submit a task for verified execution. |
| Executions | /executions | List executions, fetch a single execution, cancel one. |
| Workflows | /workflows | Multi-stage orchestrations with per-stage policy. |
| Compliance | /compliance | List built-in presets, export an execution’s compliance package. |
| Releases | /releases | Release decisions, promotions, GitHub webhook. |
| Agents | /agents | Plan verification, delegation, glass-box records. |
| Trust badge | /trust/badge | SVG trust badge for a repo + commit. |
Authentication
Every endpoint outside/auth/register and /auth/login requires an API key in the Authorization header:
POST /api/v1/auth/register or POST /api/v1/auth/login. Rotate them via POST /api/v1/auth/rotate. See Authentication for the full flow.
Response envelope
Successful responses are returned as JSON matching the documented*Response Pydantic model. Errors return a JSON body of shape:
detail field is a string for simple errors and a structured object for richer cases (for example, the task endpoint returns {"message": "...", "denied": [...]} when a request is denied by the policy ceiling).
Status codes
| Code | Meaning |
|---|---|
200 | OK. |
201 | Created (e.g. POST /tasks, POST /workflows, POST /auth/register). |
400 | Invalid policy or request body. |
401 | Missing or invalid API key. |
403 | Denied by role or policy ceiling. |
404 | Resource not found. |
422 | Request body did not validate against the Pydantic model. |
OpenAPI
Running./run.sh exposes /openapi.json and the Swagger UI at /docs for interactive exploration. The OpenAPI document is generated from the same Pydantic models the routes use, so it is always in sync with the running server.