API reference

AGENT-33 exposes a versioned REST API at http://<host>:8000, prefixed with /v1. Authentication is via bearer token (JWT or API key) carried in the Authorization header, and every route enforces an explicit scope.

This document is an operator's index of the endpoints you will actually call. For the complete, always-fresh surface (every route, every parameter, every response model), open the auto-generated Swagger UI:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

If you need to feed the spec into another tool (Postman, a code generator), download /openapi.json and use that.

Authentication

All routes except /health, /healthz, /readyz, and /v1/auth/token require a bearer token. Two token types are accepted, both passed the same way:

Authorization: Bearer <token>

JWTs expire (default 1 hour, configurable via JWT_EXPIRATION_MINUTES). API keys do not expire until revoked.

Scopes

Every protected route requires one or more scopes. Tokens carry a list; if any required scope is missing the response is 403 Forbidden.

The bootstrap admin holds all scopes. API keys you create receive a subset that you specify.

Auth (/v1/auth)

Example — mint a JWT:

curl -sX POST http://localhost:8000/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'

Response:

{ "access_token": "eyJ...", "token_type": "bearer" }

Example — create an API key:

curl -sX POST http://localhost:8000/v1/auth/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "subject":"ci-runner",
    "scopes":["agents:invoke","workflows:execute"]
  }'

The key field in the response is only shown once. Save it.

Health (/health, /healthz, /readyz)

Use /healthz from load balancers; it does not exercise downstream services. Use /health from monitoring; the response body identifies which subsystem is degraded.

Agents (/v1/agents)

The agent registry.

Example — invoke an agent:

curl -sX POST http://localhost:8000/v1/agents/researcher/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"query":"Summarize attention mechanisms","depth":"brief"}}'

Example — stream an iterative invocation (SSE):

curl -N -sX POST http://localhost:8000/v1/agents/code-worker/invoke-iterative/stream \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"task":"refactor this function"}}'

Workflows (/v1/workflows)

DAG workflow registry and runs.

Example — execute:

curl -sX POST http://localhost:8000/v1/workflows/research-assistant/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"inputs":{"topic":"hybrid retrieval","depth":"standard"}}'

Companion routes:

• GET /v1/workflows/templates/... — built-in templates index.
• GET /v1/workflow-marketplace/... — community marketplace search.
• WS /v1/workflows/runs/{run_id}/ws — live event stream (websocket).
• GET /v1/workflows/runs/{run_id}/stream — SSE event stream.

Reviews (/v1/reviews)

Two-layer review queue.

Autonomy (/v1/autonomy)

Autonomy budgets and stop conditions.

The budget state machine is DRAFT → PENDING_APPROVAL → ACTIVE → COMPLETED (or EXPIRED/CANCELED from any of the first three states).

Packs (/v1/packs)

Pack lifecycle, registry, and trust.

Traces (/v1/traces)

Tool-call and agent traces with failure taxonomy.

Evaluations (/v1/evaluations)

Golden tasks, gates, regressions.

Releases (/v1/releases)

Release lifecycle.

State machine: PLANNED → FROZEN → RC → VALIDATING → RELEASED → ROLLED_BACK.

Discovery (/v1/discovery)

Dashboard and observability

Chat and conversational surfaces

Provider/admin routes

MCP (/v1/mcp)

Model Context Protocol surface for inbound and outbound MCP integrations.

Tools and tool catalogue

Other domain routers

Error format

All errors follow FastAPI's default envelope:

{ "detail": "explanation here" }

429 responses include Retry-After and the relevant rate-limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).

Pagination

Listing endpoints accept the conventional limit and offset query parameters. The default limit is endpoint-specific (commonly 50, capped at 500). Cursor pagination is used on the high-volume endpoints (traces, events); follow the next link in the response when present.

Versioning

All routes are prefixed with /v1. Future breaking changes will ship under /v2; /v1 will continue to be served alongside it for at least one minor release cycle. The accept header is not used for versioning.

See also

• cli-reference.md — the CLI built on top of these routes.
• configuration.md — env vars that affect API behavior.
• operator-manual.md — how operators use these endpoints in practice.
• troubleshooting.md — common HTTP errors and fixes.