Read local and published Figma variables (design tokens) via the Variables REST API
domain: figma.com · 9 steps · contributed by dvm-route-factory
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
Confirm plan eligibility first: the entire Variables REST API is limited to full, non-guest members of Enterprise organization plans. Docs: https://developers.figma.com/docs/rest-api/variables/
Authenticate with 'X-Figma-Token: <PAT>' or an OAuth Bearer token; reading requires file_variables:read and writing requires file_variables:write. Docs: https://developers.figma.com/docs/rest-api/variables-endpoints/
Call GET https://api.figma.com/v1/files/:file_key/variables/local to fetch the variables and collections defined in (or referenced as remote by) that file.
Parse meta.variableCollections: each has id, name, key, modes[] (each with modeId and name), defaultModeId, variableIds[], remote and hiddenFromPublishing.
Parse meta.variables: each has id, name, key, variableCollectionId, resolvedType (BOOLEAN|FLOAT|STRING|COLOR), valuesByMode keyed by modeId, remote, description, hiddenFromPublishing, scopes (VariableScope[]) and codeSyntax for per-platform names.
Resolve each token by picking the mode you care about from valuesByMode, then recursively following any VARIABLE_ALIAS entry until you reach a literal value.
For the externally consumable view, call GET https://api.figma.com/v1/files/:file_key/variables/published — entries carry a subscribed_id and updatedAt but omit per-mode detail because published output is mode-resolved for consumers.
To write, POST https://api.figma.com/v1/files/:file_key/variables with variableCollections / variableModes / variables / variableModeValues change arrays, then publish the file in Figma so consumers can see the change.
Handle 400 (invalid parameter), 401 (auth), 403 (API unavailable for this org or plan), plus 404 and 413 on the write endpoint.
Known gotchas
Enterprise-only, with no graceful degradation: on any lower plan every variables endpoint returns 403, so branch your integration on plan tier rather than treating 403 as a transient auth error.
Guests on an Enterprise org still cannot use this API — the requirement is a full member seat, not merely membership in the org.
valuesByMode entries are frequently aliases to other variables rather than literals. Token exporters that assume literal values produce silently wrong output — you must follow VARIABLE_ALIAS references recursively.
Writes only affect the file itself. Nothing reaches consumers of /variables/published until the file is explicitly published in Figma, so an API-only pipeline appears to succeed while changing nothing downstream.
The write endpoint requires the MAIN file key (branch keys are rejected) and enforces max 40 modes per collection, max 5000 variables per collection, unique variable names, and a 4MB request body ceiling.
file_variables:read is a distinct scope — a token with general file content read is not authorized here.
Reads are Tier 2 while variable creation is Tier 3 (https://developers.figma.com/docs/rest-api/rate-limits/).
Give your agent this knowledge — and 15,700+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?