Documentation

REST API Reference

The v1 REST API is used by the CLI and third-party integrations. All endpoints live under https://app.reframeui.com/api/v1. Two authentication schemes are supported: OAuth Bearer tokens, generated in Studio under Settings → API Tokens, and API keys. All responses are JSON unless noted otherwise.

Machine-readable spec

The full API is available as an OpenAPI 3.1 JSON document. Import it into Swagger UI, Postman, Speakeasy, or any compatible tool to generate clients, run requests, or validate integrations.

Spec URLbash

https://app.reframeui.com/api/openapi.json

Authentication

Two header formats are accepted depending on the endpoint.

Bearer tokens are used by most endpoints:

Authorization: Bearer <token>

API keys are used by GET /api/v1/org:

Authorization: ApiKey <key>

Rate-limited endpoints return 429 with a Retry-After header indicating when the request can be retried.

Get current user

GET/api/v1/me

Returns the authenticated user's profile, organization membership, and accessible projects. Use this to verify that a token is valid and to inspect which projects it can access.

Auth: Bearer token.

Response 200json

{
  "id": "usr_...",
  "name": "Jane Smith",
  "email": "jane@acme.com",
  "orgId": "org_...",
  "orgName": "Acme",
  "projects": [
    { "id": "proj_...", "name": "Design System", "slug": "design-system" }
  ],
  "scopes": ["read", "publish"]
}

Terminalbash

curl https://app.reframeui.com/api/v1/me \
  -H "Authorization: Bearer <token>"

Get organization

GET/api/v1/org

Returns the organization's name, plan, and subscription status. This endpoint requires an API key rather than a Bearer token.

Auth: API key.

Response 200json

{
  "id": "org_...",
  "name": "Acme",
  "slug": "acme",
  "plan": "pro",
  "stripeSubscriptionStatus": "active",
  "trialEndsAt": null,
  "purchasedEditorSeats": 10,
  "purchasedViewerSeats": 0,
  "purchasedDesignSystems": 1
}

Terminalbash

curl https://app.reframeui.com/api/v1/org \
  -H "Authorization: ApiKey <key>"

Revoke token

POST/api/v1/auth/revoke

Revokes the Bearer token included in the request. The token is invalidated immediately. No request body is needed, and no body is returned on success.

Auth: Bearer token. Response: 204 No Content.

Terminalbash

curl -X POST https://app.reframeui.com/api/v1/auth/revoke \
  -H "Authorization: Bearer <token>"

Get latest published version

GET/api/v1/projects/:projectId/publish

Returns the version string of the most recently published release for the project. Returns null if nothing has been published yet.

Auth: Bearer token. Path parameter:

Parameter	Type	Description
projectId	string	The project ID

Response 200json

{ "version": "1.4.2" }

// or, if nothing has been published:
{ "version": null }

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../publish \
  -H "Authorization: Bearer <token>"

Publish a new version

POST/api/v1/projects/:projectId/publish

Publishes a new version of the design system. The token must belong to an editor or owner — consumer tokens receive a 403. Accepts an optional changelog message, package name, tarball URL, bump type, and a list of breaking changes. This endpoint is rate-limited.

Auth: Bearer token (editor or owner role). Request body:

Field	Type	Required	Description
version	string	Yes	Semver version string, e.g. "1.5.0"
changelog	string	No	Human-readable release notes
npmPackage	string	No	Published package name
tarballUrl	string	No	URL to the published tarball
bumpType	"patch" \| "minor" \| "major"	No	Version bump strategy
breakingChanges	string[]	No	List of breaking change descriptions

Response 201json

{
  "version": {
    "id": "ver_...",
    "projectId": "proj_...",
    "version": "1.5.0",
    "changelog": "Updated color tokens",
    "npmPackage": "@acme/design-system",
    "bumpType": "minor",
    "breakingChanges": [],
    "publishedAt": "2024-01-15T10:30:00Z"
  }
}

Terminalbash

curl -X POST https://app.reframeui.com/api/v1/projects/proj_.../publish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.5.0",
    "changelog": "Updated color tokens",
    "bumpType": "minor"
  }'

Sync project tokens

GET/api/v1/projects/:projectId/sync

Returns the full token set for the project's production branch, along with themes and components. This is what the CLI calls during reframe sync. This endpoint is rate-limited.

Auth: Bearer token.

Response 200json

{
  "project": { "id": "proj_...", "name": "Design System", "slug": "design-system" },
  "tokens": {
    "base": { ... },
    "semantic": { ... },
    "modes": { ... },
    "contexts": { ... }
  },
  "themes": [ ... ],
  "components": [ ... ]
}

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../sync \
  -H "Authorization: Bearer <token>"

Sync branch tokens

GET/api/v1/projects/:projectId/sync-branch

Returns tokens for a specific branch. Pass branchId as a query parameter to target a preview branch. Omit the parameter, or pass "main", to get production tokens. The response shape is identical to /sync. This endpoint is rate-limited.

Auth: Bearer token. Query parameter:

Parameter	Type	Required	Description
branchId	string	No	Branch ID to sync. Omit or pass "main" for production tokens.

Response 200json

{
  "project": { "id": "proj_...", "name": "Design System", "slug": "design-system" },
  "tokens": {
    "base": { ... },
    "semantic": { ... },
    "modes": { ... },
    "contexts": { ... }
  },
  "themes": [ ... ],
  "components": [ ... ]
}

Terminalbash

# Sync a preview branch
curl "https://app.reframeui.com/api/v1/projects/proj_.../sync-branch?branchId=br_..." \
  -H "Authorization: Bearer <token>"

# Sync production tokens (same as /sync)
curl "https://app.reframeui.com/api/v1/projects/proj_.../sync-branch" \
  -H "Authorization: Bearer <token>"

Get live token

GET/api/v1/projects/:projectId/live-token

Returns the live token for the project, creating one automatically if none exists. Pass this token to the reframe dev proxy to enable hot-reload during local development.

Auth: Bearer token.

Response 200json

{ "liveToken": "lt_..." }

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../live-token \
  -H "Authorization: Bearer <token>"

List branches

GET/api/v1/projects/:projectId/branches

Returns all branches for the project. The production branch (main) is always the first entry in the array. Each branch includes its id, name, status, and an optional createdAt timestamp.

Auth: Bearer token.

Response 200json

[
  { "id": "main", "name": "main", "status": "production" },
  {
    "id": "br_...",
    "name": "update-color-tokens",
    "status": "preview",
    "createdAt": "2024-01-14T09:00:00Z"
  }
]

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../branches \
  -H "Authorization: Bearer <token>"

Get docs manifest

GET/api/v1/docs/:orgSlug/:projectSlug

Returns the docs manifest for a project. If no version has been published yet, the endpoint returns 404 with {"error": "no_published_version"}.

Auth: Bearer token. Path parameters:

Parameter	Type	Description
orgSlug	string	Organization slug
projectSlug	string	Project slug

Response 200json

{
  "version": "1.5.0",
  "components": [ ... ],
  "tokens": { ... },
  "generatedAt": "2024-01-15T10:30:00Z"
}

Response 404json

{ "error": "no_published_version" }

Terminalbash

curl https://app.reframeui.com/api/v1/docs/acme/design-system \
  -H "Authorization: Bearer <token>"

Error responses

All endpoints return standard HTTP status codes. Error bodies include an error field with a machine-readable key.

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — token missing or invalid
403	Forbidden — consumer role cannot publish
404	Not found — project or resource does not exist
429	Rate limited — check the `Retry-After` header

Next steps

Using the CLI? The CLI Reference covers the commands that call these endpoints and how to configure your local setup.

CLI Reference →

Documentation

REST API Reference

Machine-readable spec

The full API is available as an OpenAPI 3.1 JSON document. Import it into Swagger UI, Postman, Speakeasy, or any compatible tool to generate clients, run requests, or validate integrations.

Spec URLbash

https://app.reframeui.com/api/openapi.json

Authentication

Two header formats are accepted depending on the endpoint.

Bearer tokens are used by most endpoints:

Authorization: Bearer <token>

API keys are used by GET /api/v1/org:

Authorization: ApiKey <key>

Rate-limited endpoints return 429 with a Retry-After header indicating when the request can be retried.

Get current user

GET/api/v1/me

Returns the authenticated user's profile, organization membership, and accessible projects. Use this to verify that a token is valid and to inspect which projects it can access.

Auth: Bearer token.

Response 200json

{
  "id": "usr_...",
  "name": "Jane Smith",
  "email": "jane@acme.com",
  "orgId": "org_...",
  "orgName": "Acme",
  "projects": [
    { "id": "proj_...", "name": "Design System", "slug": "design-system" }
  ],
  "scopes": ["read", "publish"]
}

Terminalbash

curl https://app.reframeui.com/api/v1/me \
  -H "Authorization: Bearer <token>"

Get organization

GET/api/v1/org

Returns the organization's name, plan, and subscription status. This endpoint requires an API key rather than a Bearer token.

Auth: API key.

Response 200json

{
  "id": "org_...",
  "name": "Acme",
  "slug": "acme",
  "plan": "pro",
  "stripeSubscriptionStatus": "active",
  "trialEndsAt": null,
  "purchasedEditorSeats": 10,
  "purchasedViewerSeats": 0,
  "purchasedDesignSystems": 1
}

Terminalbash

curl https://app.reframeui.com/api/v1/org \
  -H "Authorization: ApiKey <key>"

Revoke token

POST/api/v1/auth/revoke

Revokes the Bearer token included in the request. The token is invalidated immediately. No request body is needed, and no body is returned on success.

Auth: Bearer token. Response: 204 No Content.

Terminalbash

curl -X POST https://app.reframeui.com/api/v1/auth/revoke \
  -H "Authorization: Bearer <token>"

Get latest published version

GET/api/v1/projects/:projectId/publish

Returns the version string of the most recently published release for the project. Returns null if nothing has been published yet.

Auth: Bearer token. Path parameter:

Parameter	Type	Description
projectId	string	The project ID

Response 200json

{ "version": "1.4.2" }

// or, if nothing has been published:
{ "version": null }

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../publish \
  -H "Authorization: Bearer <token>"

Publish a new version

POST/api/v1/projects/:projectId/publish

Auth: Bearer token (editor or owner role). Request body:

Field	Type	Required	Description
version	string	Yes	Semver version string, e.g. "1.5.0"
changelog	string	No	Human-readable release notes
npmPackage	string	No	Published package name
tarballUrl	string	No	URL to the published tarball
bumpType	"patch" \| "minor" \| "major"	No	Version bump strategy
breakingChanges	string[]	No	List of breaking change descriptions

Response 201json

{
  "version": {
    "id": "ver_...",
    "projectId": "proj_...",
    "version": "1.5.0",
    "changelog": "Updated color tokens",
    "npmPackage": "@acme/design-system",
    "bumpType": "minor",
    "breakingChanges": [],
    "publishedAt": "2024-01-15T10:30:00Z"
  }
}

Terminalbash

curl -X POST https://app.reframeui.com/api/v1/projects/proj_.../publish \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.5.0",
    "changelog": "Updated color tokens",
    "bumpType": "minor"
  }'

Sync project tokens

GET/api/v1/projects/:projectId/sync

Returns the full token set for the project's production branch, along with themes and components. This is what the CLI calls during reframe sync. This endpoint is rate-limited.

Auth: Bearer token.

Response 200json

{
  "project": { "id": "proj_...", "name": "Design System", "slug": "design-system" },
  "tokens": {
    "base": { ... },
    "semantic": { ... },
    "modes": { ... },
    "contexts": { ... }
  },
  "themes": [ ... ],
  "components": [ ... ]
}

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../sync \
  -H "Authorization: Bearer <token>"

Sync branch tokens

GET/api/v1/projects/:projectId/sync-branch

Auth: Bearer token. Query parameter:

Parameter	Type	Required	Description
branchId	string	No	Branch ID to sync. Omit or pass "main" for production tokens.

Response 200json

{
  "project": { "id": "proj_...", "name": "Design System", "slug": "design-system" },
  "tokens": {
    "base": { ... },
    "semantic": { ... },
    "modes": { ... },
    "contexts": { ... }
  },
  "themes": [ ... ],
  "components": [ ... ]
}

Terminalbash

# Sync a preview branch
curl "https://app.reframeui.com/api/v1/projects/proj_.../sync-branch?branchId=br_..." \
  -H "Authorization: Bearer <token>"

# Sync production tokens (same as /sync)
curl "https://app.reframeui.com/api/v1/projects/proj_.../sync-branch" \
  -H "Authorization: Bearer <token>"

Get live token

GET/api/v1/projects/:projectId/live-token

Returns the live token for the project, creating one automatically if none exists. Pass this token to the reframe dev proxy to enable hot-reload during local development.

Auth: Bearer token.

Response 200json

{ "liveToken": "lt_..." }

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../live-token \
  -H "Authorization: Bearer <token>"

List branches

GET/api/v1/projects/:projectId/branches

Returns all branches for the project. The production branch (main) is always the first entry in the array. Each branch includes its id, name, status, and an optional createdAt timestamp.

Auth: Bearer token.

Response 200json

[
  { "id": "main", "name": "main", "status": "production" },
  {
    "id": "br_...",
    "name": "update-color-tokens",
    "status": "preview",
    "createdAt": "2024-01-14T09:00:00Z"
  }
]

Terminalbash

curl https://app.reframeui.com/api/v1/projects/proj_.../branches \
  -H "Authorization: Bearer <token>"

Get docs manifest

GET/api/v1/docs/:orgSlug/:projectSlug

Returns the docs manifest for a project. If no version has been published yet, the endpoint returns 404 with {"error": "no_published_version"}.

Auth: Bearer token. Path parameters:

Parameter	Type	Description
orgSlug	string	Organization slug
projectSlug	string	Project slug

Response 200json

{
  "version": "1.5.0",
  "components": [ ... ],
  "tokens": { ... },
  "generatedAt": "2024-01-15T10:30:00Z"
}

Response 404json

{ "error": "no_published_version" }

Terminalbash

curl https://app.reframeui.com/api/v1/docs/acme/design-system \
  -H "Authorization: Bearer <token>"

Error responses

All endpoints return standard HTTP status codes. Error bodies include an error field with a machine-readable key.

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — token missing or invalid
403	Forbidden — consumer role cannot publish
404	Not found — project or resource does not exist
429	Rate limited — check the `Retry-After` header

Next steps

Using the CLI? The CLI Reference covers the commands that call these endpoints and how to configure your local setup.

CLI Reference →