API & MCP Overview

What this is

GRAILS extracts your design system from Figma at sync time and stores it. The API and the MCP server let you query that stored copy — from a build script, from CI, or from an AI coding agent.

Sync time    Figma plugin  →  captures & normalises  →  GRAILS
Query time   Your agent    →  API / MCP              →  GRAILS

Figma is never in the query-time path

Reading a component spec does not open your Figma file, does not need your Figma session, and does not count against Figma’s rate limits. It reads what the last sync captured. That also means the answer is exactly as fresh as your last sync — see last_synced_at on any component.

The surface is read-only for design system data. The one exception is documentation, which the API can also write.

Two transports, one API

REST	https://api.grails.design/v1/…
MCP	https://api.grails.design/mcp/v1

They are the same application over the same data, and they authenticate with the same API key. There is no separate MCP login and no OAuth flow.

Pick REST for build scripts, CI checks and anything that fits a URL. Pick MCP when an AI agent is the consumer — the tools carry descriptions the agent reads before calling them.

Getting a key

Team settings → Integrations → Manage API keys.

Any admin or editor can create their own key. Keys look like this:

grails_sk_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

The secret is shown once and never stored

GRAILS keeps only a hash. If you lose the key you cannot recover it — you create a new one and delete the old. That is deliberate: a key we could show you again is a key an attacker could read out of our database.

A key expires after 90 days by default, and you get an email 7 days and 1 day before. Rotating early gives you a 7-day overlap where both keys work, so nothing breaks mid-deploy.

Removing a member from the team deletes their keys immediately.

Scopes

A key carries a set of scopes. There are eight.

Scope	What it opens
read:library	Everything this API reads from your design system: components and their specs, build order, validation, entity search and the graph, design tokens and their resolved values per mode, styles and their properties, drift and health
read:docs	Read documentation. Also validates it — a dry run writes nothing
write:docs	Create, update and delete documentation
write:code	Upload your code components and design tokens with the Grails Code Sync CLI (REST only, /v1/code/*)
write:tokens	Edit how your code’s tokens are matched to Figma’s: the naming rules of each code source and the colour threshold (REST and MCP)
read:patterns	Read your project’s patterns: the list, and one pattern whole with whether it still fits your design system
write:patterns	Create and replace patterns, drafts and published alike. It does not include reading them
write:pairing	Link and unlink which part of a Figma component is which part of its code component: elements, props and their values. It does not include reading them

write:docs, write:code, write:tokens, write:patterns and write:pairing are the ones to think about. They are the only permissions on this API that change anything (write:patterns creates patterns and replaces them whole, write:pairing links and unlinks a component’s design and code parts): write:docs edits and deletes documentation, write:code uploads code components and design tokens (a complete upload can mark components deleted in code), and write:tokens edits and deletes the naming rules that the code ↔ Figma token match applies. Everything else is read-only, fed by the Figma sync. A key that reads your design system and cannot touch your documentation is read:library plus read:docs.

Where the two read scopes divide: the fragment, not the entity

read:library and read:docs both read, so it is worth being precise about what separates them — and it is not a kind of entity. It is how much of a document travels:

read:library	the fragment that matched a search, and the passage of a mention
read:docs	the blocks themselves, structured, with their mentions resolved

So a catalogue-only key can tell you a page discusses your token, and quote the sentence. Reading the page is read:docs.

Scope checks are exact. There is no read:* wildcard, so a key without read:library gets a 403 — with the missing scope named in the error, so you know what to add. Over MCP it is the tool that refuses, not the connection: see Answers about your key.

These were eight until September 2026

read:components, read:tokens, read:artifacts, read:drift, read:health and read:design_systems are gone; they are all read:library now. They split the surface by kind of entity while every real question crosses kinds — what does this component use, what breaks if I change this token — so the split cost you permissions without protecting anything: token names were already visible in a component’s spec to any key that could read the component.

You do not need to do anything. Existing keys were migrated in place and keep working.

Rate limits

Every key has a requests-per-minute figure, 60 by default.

Monitored, not enforced

Today the platform counts requests and logs when a key goes over. No request is rejected for going too fast — you will not see a 429 from us. The counter exists so we can size the limit against real usage before it starts blocking. Treat the number as a budget, not a wall, and do not build retry logic around a 429 you will not receive yet.

Every response to an authenticated request carries four headers — success and error alike:

Header	Meaning
X-RateLimit-Limit	Your key’s requests-per-minute
X-RateLimit-Remaining	What is left in the current minute — may be absent, see below
X-RateLimit-Reset	Unix epoch seconds when the window ends — an absolute instant, not a countdown
X-RateLimit-Enforced	false today. Read this one first

Read X-RateLimit-Enforced before you act on the other three

The three standard headers, on their own, would mislead you here. Remaining: 0 normally means the next request gets a 429 — and it does not, because the counter never blocks. The fourth header says so in the channel a machine reads, so your client does not have to encode a policy it cannot see. When it turns true, 429 becomes real and Reset tells you when to retry.

Reset is an absolute epoch rather than “N seconds from now” on purpose: a delta forces your client to know when the response was issued, and network latency or a retry puts that out of step.

Three things Remaining does not promise

If X-RateLimit-Remaining is absent, do not read it as zero — read it as “could not be counted”. A client that treats a missing header as 0 stops itself for no reason. The header is omitted rather than filled with the limit because publishing the full limit would be inventing the most reassuring answer, said by something that counted nothing. The other three headers are always present.

The sequence is not monotonic. The count is kept per edge location, so consecutive requests from the same client can read 58 and then 59 again — your requests landed in different locations. If your client assumes the number only ever goes down, it will read that as a window reset that did not happen. Use X-RateLimit-Reset for the window, never a drop in Remaining.

X-RateLimit-Limit is your key’s configured ceiling, not an effective global one. With the counter kept per location, a client spread across several can do more than the stated number before anything notices. That is harmless while X-RateLimit-Enforced is false — nothing is applied — but it is the number that would have to change first the day it turns true.

A request rejected for a missing or invalid key carries none of them, and that is deliberate: all four describe a specific key’s budget, and there is no key to describe. Neither does a 403 for a plan without API access (GRAILS_AUTH_PLAN_REQUIRED) nor a 503: the gateway answers those before it counts. All four are readable from browser JavaScript — they are in the CORS expose list, not merely sent. The OpenAPI document declares them on each response, in components.headers: three required and X-RateLimit-Remaining optional, and none required on a 403, which the gateway can answer too.

Reading the contract

/docs	Every operation, its scope and its parameters — readable, no credential
/openapi.json	The same thing, for a machine

Both are public, and for the same reason: a contract you need a credential to read cannot help you decide whether to ask for a credential.

Why there is no “Try it out” console

/docs is generated from the OpenAPI document but deliberately loads no third-party scripts. The interactive consoles that usually fill this role are fetched from a CDN and ask you to paste an API key into the page — and this page is public. A credential pasted into a public page that runs code from another domain is not worth the convenience of firing a request from the browser.

Use curl; the MCP and REST pages have the commands ready.

An OpenAPI 3.1 document, generated from the same schemas the server validates against. A test fails the build if a route exists that the document does not describe, so it cannot drift out of date by omission.

3.1 means the schemas are JSON Schema

OpenAPI 3.1 is JSON Schema 2020-12, which is the same dialect the MCP tools publish. If you generate a client from this document, the types you get match the ones an MCP client sees.

Errors

Every error has the same shape, on both transports:

{
  "error": {
    "code": "GRAILS_NOT_FOUND",
    "message": "Component with id '…' not found in this project",
    "status": 404,
    "request_id": "req_abc123def456",
    "details": { "entity": "Component", "id": "…" }
  }
}

Branch on code, never on message — messages get clearer over time, codes do not change. Include request_id when you report a problem; it is how we find your exact request.

Answers about your key

These are decided before your request reaches the API, so they arrive the same way on both transports: as the HTTP status of the request itself — for MCP, of the POST to /mcp/v1.

Status	code	What it means	What to do
401	GRAILS_AUTH_MISSING_TOKEN	No Authorization: Bearer <key> header, or a malformed one	Send the header
401	GRAILS_AUTH_INVALID_TOKEN	No key matches what you sent	Check you copied the whole key. If it was deleted, create a new one
401	GRAILS_AUTH_REVOKED_TOKEN	The key was revoked	Create a new key, or ask a team admin
401	GRAILS_AUTH_EXPIRED_TOKEN	The key is past its expiry date	Rotate it
403	GRAILS_AUTH_PLAN_REQUIRED	The team’s plan does not include API access	A plan change. No key and no retry fixes it
503	GRAILS_SERVICE_UNAVAILABLE	We could not check your key right now	Your key is fine. Wait the seconds in Retry-After and retry

Every 401 carries WWW-Authenticate: Bearer realm="grails". There is no OAuth flow behind it — the fix is always the key, as the table says.

Do not rotate or delete a key on a 503

A 503 says we could not ask, not that the answer was no. It says nothing about your key, and replacing the key changes nothing: retry after Retry-After.

A missing scope is the one that differs by transport, because the key itself is valid:

REST	403 GRAILS_AUTH_INSUFFICIENT_SCOPE, with details.required_scope, and WWW-Authenticate: Bearer error="insufficient_scope", scope="<the scope>"
MCP	The connection works; that one tool answers with isError and the same code in its result. The other tools stay usable

Either way the fix is a key that carries that scope.

A 404 does not distinguish “gone” from “not yours”

An id belonging to another team returns exactly what a nonexistent id returns. That is on purpose: telling the two apart would let anyone map other teams’ component ids by probing. If you get a 404 on an id you believe exists, check you are using the key for the right project.

What “this project” means

Your key belongs to one project, and every request operates on it. There is no project_id parameter anywhere — not in a URL, not in a body, not in an MCP tool argument. Sending one has no effect; it is ignored, not honoured.

If you work across several projects, you need a key per project.

Where to go next

• MCP tools — connect Claude Code, Cursor or another agent, and what each tool does
• REST endpoints — the routes, their parameters and their responses
• Reading responses — the fields you have to read before the data, and why. Start here if you are writing anything that consumes these responses programmatically.