API reference

The API is JSON over HTTPS except for server-sent events and CSV/PDF exports. FastAPI also exposes generated OpenAPI JSON and Swagger UI at the API host.

Authentication#

Protected routes require:

Authorization: Bearer <clerk-session-token>

Public API routes are /api/health, /api/readiness, /api/billing/webhook, and /api/runs/stream. The chat webhook uses an HMAC signature or a matching Clerk organization identity. The public SSE route still requires a scoped stream token in its own handler.

After authentication, middleware resolves the user’s application role and enforces a route-specific permission. Read routes generally require app:read; sensitive reads and all writes use their documented operational permission. An unmapped write route defaults to admin:all.

Health and identity#

Runs, metrics, and exports#

Approval routes also expose POST /api/runs/start and POST /api/runs/{run_id}/execute.

Approvals and backlog#

Settings, features, and billing#

Role administration#

Only a Clerk organization administrator receives roles:manage and billing:manage. Neither permission can be added through a database role assignment.

Request example#

curl --request GET \
  --header "Authorization: Bearer <clerk-session-token>" \
  "https://<api-host>/api/runs?limit=20&offset=0&board_type=taiga"

Response example#

[
  {
    "id": "<run-id>",
    "board_type": "taiga",
    "project_key": "example-project",
    "status": "completed",
    "is_dry_run": true,
    "planned_actions_count": 3,
    "executed_actions_count": 0,
    "cycles_run": ["A", "D"]
  }
]

Errors and status codes#

FastAPI handler errors commonly use {"detail":"..."}. Authentication and rate-limit middleware use {"error":"..."}. An authorization denial returns HTTP 403 with detail.error, detail.required_permission, and detail.role. Expect 400 for invalid input, 401 for missing or invalid identity, 403 for authorization, tenant, or plan restrictions, 404 for missing scoped resources, 409 for terminal-state conflicts, 413 for oversized transcripts, 429 for rate limiting, 500 for server errors, and 503 when authorization dependencies are unavailable.

Pagination, filtering, and sorting#

GET /api/runs uses limit and offset and sorts newest first. Other list routes use documented filters but do not share one universal pagination envelope. There is no general public sorting parameter.

Rate limits#

Defaults are 200 reads and 60 writes per minute per derived key. A 429 response includes Retry-After and retry_after_seconds. The limiter is process-local and environment-configurable, so these defaults are not a multi-instance service guarantee.