About the OpenAPI spec

The platform exposes a complete OpenAPI 3.1.0 specification for every public endpoint. Every request and response is described by a Pydantic model — there are no untyped dict[str, Any] payloads in the spec.

Where to fetch it

Three URLs, all served by the API container:

Path	Purpose
GET /openapi.json	The raw OpenAPI 3.1 JSON. Stable URL — point your tooling here.
GET /docs	Swagger UI explorer (FastAPI built-in).
GET /redoc	ReDoc renderer (FastAPI built-in).

Substitute your API host. These are the FastAPI defaults and are enabled out of the box.

A handful of routes are exposed but not listed in the spec because they aren’t registered as FastAPI route handlers: /metrics (Prometheus exposition wired into the ASGI app via api/observability.py), /docs, /redoc, and /openapi.json itself (FastAPI internals). Treat these four paths as out-of-band by convention.

Tip

The same spec is rendered interactively under API Reference in this docs site — that view is generated at build time from a snapshot of /openapi.json so the docs site is fully static.

Refreshing the snapshot in this docs site

The interactive API Reference reads from public/openapi.json. Refresh it whenever the API surface changes:

# From the repository root; no running API is required:
.venv/bin/python scripts/check_openapi_snapshot.py --update
node docs-site/scripts/enrich-openapi.mjs

# Then rebuild the static site:
npm --prefix docs-site run build

Backend CI compares this committed snapshot to app.openapi() and fails on route or schema drift. npm run sync:openapi is still available from the docs-site/ directory when you need to compare a running deployment. The docs container bundles the committed snapshot.

Code generation

The OpenAPI spec is suitable for:

• TypeScript clients — openapi-typescript (npx openapi-typescript http://localhost:8080/openapi.json -o api.ts) or openapi-fetch.
• Python clients — openapi-python-client or hand-written httpx against the spec.
• Go clients — oapi-codegen.
• Java / Kotlin clients — openapi-generator.

We ship no first-party SDKs. The spec is the contract; generate what fits your stack.

See also

• Contract testing — automated fuzz tests that verify the running API against its own OpenAPI spec, catching drift before integrators hit it.
• Integration guide §16.4 — operator notes on the OpenAPI surface (including how to disable Swagger / ReDoc in hardened deployments).