Internal API reference

Generated reference for our internal APIs belongs here, under reference/api/, one section per service. Each service’s own schema produces it — an OpenAPI document committed in the service repo. Never hand-edit the result. A wrong generated page means a wrong schema: fix it there and regenerate.

That rule is the whole point of generating. The reference cannot drift from the API, because nobody maintains a second copy of it.

The legacy Apps API output

The previously published Apps API reference is still served, unchanged, from /apps-api/. It is a Redoc bundle committed under public/apps-api/ in this repo, frozen: no workflow regenerates it, and nothing in this repo should edit it.

The YAML beside that bundle is not what serves it. public/apps-api/index.html carries the whole specification inlined and renders it in the browser, so it never reads the openapi.yaml, introduction.md or schemas.yaml files next to it, and nothing in this repo rebuilds them. Editing those files changes nothing on the page — they are inert, not merely stale.

It stays there until the public API documentation moves to its own home. When that migration completes, we delete public/apps-api/ and add a Cloudflare redirect rule pointing the old URLs at the new location.