OpenAPI Spec
Where the spec lives, how to browse it, and how it's kept current.
Where it lives
- Static file:
public/openapi.yaml, served at/openapi.yamlon any deployed registry. - API route:
GET /api/openapiserves the same YAML with CORS headers, so it's the one to point Swagger UI / Redoc / Postman at from a browser or another origin. The route reads and serves the file directly, no codegen step. - Every registry page links to
/developerin its footer, which is where the interactive API explorer lives; the raw YAML isn't linked from the footer directly.
The spec is OpenAPI 3.1, versioned independently of the app itself
(info.version: 2.0.0-alpha at the time of writing), it tracks the pre-1.0 release series and
will start incrementing on breaking changes once the API stabilizes.
What it documents, and what it doesn't yet
The spec is the primary route reference for this pillar and covers every cluster below: registry
push/read, sync, the session-authenticated /api/handoff/* surface (content CRUD, changelog,
AI, admin, Figma, account), OAuth device authorization, and /api/mcp.
The spec covers well under half the route tree
openapi.yaml documents 40 paths; handoff-app ships 131 route handlers under
src/app/app/api/, and the spec was last touched on 2026-06-19. It's a useful reference for
the surfaces it does cover, but it is not a complete or current inventory, read the route
handlers when the answer matters.
Named gaps this pillar calls out where it's material, rather than inventing schema for what
isn't spec'd: the modern OAuth 2.1 connector flow (/api/oauth/register, /authorize,
/authorization-server-metadata, /protected-resource-metadata) exists in code (see
/api/oauth) but isn't in openapi.yaml; most of the ai/* and
admin/* surface is undocumented; POST /api/sync/upload's documented 207 response is never
returned by the code; and the Figma plugin's own REST surface (/api/figma-plugin/*) is a
separate contract not covered by this spec or this pillar at all.
Keeping it current
Per AGENTS.md's checklist for adding a data type: every new/changed route updates paths: and
any new components/schemas: in the same PR, and info.version tracks the release milestone.
There's no codegen, the spec is hand-maintained alongside the route handlers it describes.