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 docs-site/ directory, against a running API:
API_URL=http://localhost:8080 npm run sync:openapi

# Then rebuild the static site:
npm run build

In CI this typically runs after the API container’s health check passes. The docs container’s Dockerfile bundles the snapshot that was committed to git, so a build that needs absolutely-fresh API surface should regenerate it first.

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).