# 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`](http://localhost:8080/openapi.json) | The raw OpenAPI 3.1 JSON. Stable URL — point your tooling here. |
| [`GET /docs`](http://localhost:8080/docs) | Swagger UI explorer (FastAPI built-in). |
| [`GET /redoc`](http://localhost:8080/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](/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](/api-reference/) reads from `public/openapi.json`. Refresh it whenever the API surface changes:

```bash
# 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](/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](/integration-guide/#164-openapi--swagger)** — operator notes on the OpenAPI surface (including how to disable Swagger / ReDoc in hardened deployments).