HTTP API
The routes a Handoff 2.1.0 server exposes, which credential each needs, and which ones are stable to call.
A running workspace and a registry serve the same documentation app with Next.js API routes. Most routes exist for the app itself, the CLI, or MCP. For programmatic access, prefer the MCP tools, the CLI, or the JavaScript API; the route shapes below are not a versioned public contract.
Credentials
| Credential | Header |
|---|---|
| Access token or device login | Authorization: Bearer hnd_... or X-Handoff-Api-Key: hnd_... |
HANDOFF_SYNC_SECRET | Same headers |
| Browser session | Cookie set by sign-in |
Mutating methods (POST, PUT, PATCH, DELETE) on registry routes need registry:write. Reads
need registry:read. See Accounts and access.
Docs read API
GET only, no credential, in a workspace and in a registry. The documentation app reads through it.
| Route | Returns |
|---|---|
/api/docs/components.json | Every component |
/api/docs/components/{id}.json | One component, with build state |
/api/docs/components/{id}/previews/{previewId} | A rendered preview |
/api/docs/components/{id}/inspect/{previewId} | A preview in inspect mode |
/api/docs/components/{id}/assets/{asset} | A built asset of the component |
/api/docs/patterns.json, /api/docs/patterns/{id}.json | Patterns |
/api/docs/patterns/{id}/preview | A rendered pattern |
/api/docs/tokens/foundations/{type}.json | Foundation tokens, for example colors |
/api/docs/tokens/components/{id}.json | Component tokens |
/api/docs/assets/{collection} and /{...path} | Icon and logo collections, files, and zip archives |
/api/docs/search/pages.json?q=&group=&limit= | Ranked page search |
/api/docs/nav.json | Navigation |
Registry only: /api/docs/components/{id}/custom-previews lists a component's
custom previews, and .../{customId}/render serves one in its
sandboxed render shell.
Registry API
Registry mode only. A workspace answers 409.
| Route | Methods | Purpose |
|---|---|---|
/api/registry/health | GET | Liveness and transfer capabilities. No credential. |
/api/registry/transfer/{component|pattern|page} | GET | List published entities |
/api/registry/transfer/{kind}/{id} | GET, PUT | Read or publish one entity package |
/api/registry/transfer/tokens, /tokens/{...setId} | GET, PUT | Token sets |
/api/registry/transfer/assets, /assets/{collection} | GET, PUT | Asset collections |
/api/registry/transfer/assets/blobs/have | POST | Ask which blob hashes the registry already has |
/api/registry/transfer/assets/blobs/{hash} | GET, PUT | Read or upload a blob through the registry |
/api/registry/transfer/assets/blobs/{hash}/upload, /complete | POST | Start and finish a direct upload to storage |
/api/registry/components, /patterns, /pages | GET, POST and per-id GET, PUT, DELETE | Entity records and their files |
/api/sync/upload | POST | Compatibility route for older push clients |
Other routes
| Route | Purpose |
|---|---|
/api/mcp/ | MCP endpoint |
/api/ai/chat, /api/ai/connections | AI assistant |
/api/custom-previews, /api/custom-previews/{customId} | Create (POST), change (PATCH), and delete (DELETE) custom previews, signed in |
/api/oauth/device, /api/oauth/device/approve, /api/oauth/token, /api/oauth/revoke | Device-code login for the CLI |
/api/auth/*, /api/account/*, /api/admin/users/* | Sign-in, account settings, tokens, AI keys, and user management |
/api/install | The first-administrator installer |
A static site has no API routes.