/api/registry
The push/read endpoints a workspace uses to sync data to its registry.
One push endpoint per data type, each writing into its own singleton row (or, for theme.css,
serving a compiled artifact). All POST endpoints require a sync bearer with sync:write, see
Auth & scopes. Called in sequence by handoff-app push:all, see
Workspace → CLI reference.
| Endpoint | Read | Payload |
|---|---|---|
POST /api/registry/config | GET /api/registry/config (public) | The app block from handoff.config.* — title, client, breakpoints, sort orders, etc. |
POST /api/registry/theme | GET /api/registry/theme.css (public, compiled CSS) | Theme CSS content. |
POST /api/registry/navigation | Served via getDataProvider() | The page navigation tree, derived from pages/. |
POST /api/registry/pages | GET /api/registry/pages (public, returns every page as a summary list, no query params) | All markdown pages + frontmatter. |
POST /api/registry/tokens | GET /api/registry/tokens | The raw Figma token snapshot (localStyles.{color,typography,effect}). |
POST /api/registry/dtcg | GET /api/registry/dtcg (+ GET /api/registry/dtcg/download) | The compiled DTCG manifest + css/scss/tailwind/dtcg dist output, see Token pipeline. |
POST /api/registry/icons | GET /api/registry/icons (+ download) | The icon catalog (IconCatalogEntry[]). |
POST /api/registry/logos | GET /api/registry/logos (+ GET /api/registry/logo.svg) | The logo set (LogoSet). |
POST /api/registry/fonts | — | Font files served back at /fonts/<file>; consumed by theme.css and foundation raster previews. |
A few endpoints outside the push:all table above cover narrower, related data: POST /api/registry/assets/ingest (and /ingest-figma-fills) is the per-image push path used by the
image-reference rewrite system during component push (see
/api/sync); POST /api/registry/image-slots pushes image slot sizing
specs extracted from Figma; GET/POST /api/registry/components/{id}/previews manage individual
component preview records directly.
GET /api/registry/config is a public read
Unlike the write side, GET /api/registry/config needs no auth at all; it's called from the
client bundle for runtime branding (title, theme, etc.), so it has to be reachable before any
session exists.
Example: pushing config
curl -X POST https://your-registry.example.com/api/registry/config \
-H "Authorization: Bearer $HANDOFF_SYNC_SECRET" \
-H "Content-Type: application/json" \
-d '{"data": {"title": "My Design System", "client": "Acme Co."}}'The { "data": { ... } } envelope is specific to /config. Each other endpoint takes its own
top-level key:
| Endpoint | Body |
|---|---|
POST /api/registry/config | { data } |
POST /api/registry/theme | { css } (a string) |
POST /api/registry/navigation | { tree } (a NavigationNode[]) |
POST /api/registry/pages | { pages } |
POST /api/registry/tokens | { payload } (+ optional message) |
POST /api/registry/dtcg | { manifest, css, scss, tailwind, dtcg } (+ optional brands) |
POST /api/registry/icons | { catalog } (an array) |
POST /api/registry/logos | { logoSet } |
POST /api/registry/fonts | { fonts } (an array) |
Whatever the key, every one of these replaces the singleton row wholesale (no partial-merge
semantics), re-running push:all is always safe.