Token version to GitHub PR

When you finish, a published token-set version is on your repo as an open pull request instead of only living in Sorb. You need a project with GitHub connected and a committed token-set version. This is a fully automated pipeline, driven from the dashboard or this API — it is separate from the Figma plugin's own Open PR button, which is a manual, clipboard-assisted flow (see Use the Sorb plugin in Figma) and does not call this route.

What it does

POST /api/projects/:id/token-pr takes a token-set version you already committed, renders it to a CSS stylesheet (the same generator the dashboard preview uses), and opens a pull request with that stylesheet as the diff. It never touches uncommitted or preview-only tokens — only a version that has already been committed to the set's history.

If the set has a paired dark-mode sibling, its published HEAD is included in the same stylesheet automatically; the PR body says so.

From the dashboard

You don't have to call the API directly. In a project's Publish tab (the Compare view, /dashboard/projects/:id/tokens/compare) pick the two versions you're comparing, then click Open PR — the button calls this same route with the selected "head" version as version and the selected "base" version as baseVersion.

Request

POST /api/projects/:id/token-pr
Authorization: <session, or Bearer <project-key> with write scope>
Content-Type: application/json

{ "setId": "<token-set-uuid>", "version": 3, "baseVersion": 2 }

What the PR contains

• One file changed — the project's configured token stylesheet path, replaced with the full rendered output for version (and the dark sibling's HEAD, if one exists). The PR is additive to your repo's history in the sense that it never rewrites anything but that one file; it does not merge itself.
• A rendered diff in the PR body — when baseVersion is given, the body lists what changed between the two versions (added/removed/changed, with a breaking-change count) and links back to the compare view in the Sorb dashboard.
• Title — Design tokens <set> v<from> → v<to> — N changes when a diff was computed, or a plain Design tokens — <set> v<version> otherwise.

Branch key & idempotency

The PR's branch is sorb/{projectShortId}/tokens-v{N} — deterministic per project and version. Calling this route again for the same project and version finds the existing branch/PR instead of opening a duplicate:

{ "existing": true, "prUrl": "https://github.com/…", "prNumber": 42 }

A first-time call for that version returns the same shape with "existing": false.

Prerequisites

• GitHub must be connected on the project (the GitHub App install, or a configured personal access token) by an org admin. Without it, the route returns pr_not_configured — connect GitHub from the project's dashboard settings first.
• The caller needs approve_merge — a session user must hold that org role; a Bearer key's write scope is its own authorization.
• Every token in the version must be emittable as CSS. A non-scalar value (an object or array where a single value belongs) fails the request before anything is written to GitHub.

Errors

Next

• Tokenize a repo — the other pipeline that opens a PR, for a repo that has no tokens yet.
• Cloud REST API — the full route reference.
• Cloud & accounts — connect GitHub and manage keys.

Works with Figma. Not affiliated with, or endorsed by, Figma. Figma is a trademark of Figma, Inc.