What the Figma REST API lets an agent read or change

Someone asks the agent to inspect the primary button in a shared library. The agent calls GET file on the library key, pulls the entire document, and then posts a comment on the component so "the designer sees the note." The comment is now in a file dozens of products subscribe to. The read was fine. The comment was a write, in public, on the source of truth.

This post is the Figma REST split that matters for an agent: node ids for reads, the seat-based rate limit on those reads, and the short list of REST calls that actually change a file.

Start from the node id

A Figma URL carries a file key and, often, a node id. In the URL the node looks like 1-2. The REST API wants 1:2. GET /v1/files/{key} returns the document. GET /v1/files/{key}/nodes?ids=1:2 returns the nodes you name. You can pass more than one id in that ids parameter and pay for one request.

That distinction is the whole read strategy. A design agent that re-fetches the library file on every turn will hit the ceiling long before it has a useful answer. A design agent that stores file key plus 1:2 can ask for the button.

The Figma REST catalog page lists what Swytchcode has downloaded for this provider. Run swy search figma and then swy list methods. Enable the node read. Leave comment and variable writes off until a person has asked for them.

swy search figma
swy list methods

There is no .env file in this project. Swytchcode keeps credentials in its own local store and reads them when a call runs. A Figma personal access token is an account-wide credential. It should not sit in the prompt.

The read limit depends on the seat and the file's plan

Figma's rate limit table, in effect since November 17, 2025, puts GET file, GET file nodes, and GET image in Tier 1. Limits are per minute unless the table says otherwise, and they follow the seat of the user and the plan of the file.

For a View or Collab seat, Tier 1 is up to 20 requests a month, on every plan column in that table. Figma also says the real number can be lower when traffic is high. A Dev or Full seat on Professional is 10 a minute for Tier 1. Organization is 15 a minute. Enterprise is 20 a minute. A Starter file does not inherit the Enterprise limit just because the token owner has an Enterprise seat somewhere else. The file's plan wins.

Personal access tokens count against the user who minted them, per plan. Two teammates running one script with Mei's token share Mei's budget. OAuth apps are tracked per user, per plan, per app, so one app burning the budget does not spend a second app's budget.

A 429 comes back with Retry-After in seconds, X-Figma-Plan-Tier, X-Figma-Rate-Limit-Type (low for View and Collab, high for Full and Dev), and X-Figma-Upgrade-Link. Honor Retry-After. Hammering the endpoint spends the monthly View budget on failures.

Connecting Notion has a similar shape for documents: read the block you were asked about. Figma's version of that mistake is more expensive because Tier 1 on a View seat is a monthly counter, not a per-minute one.

REST writes are comments, copies, and variables

The REST API is not a general "edit this frame" interface. Layout edits of that kind belong to Figma's plugin API, which runs inside the file. The REST writes you should treat as dangerous are the ones the rate-limit page actually lists.

Comments sit in Tier 2. POST variables sits in Tier 3. POST duplicate file sits in Tier 2. A comment on a shared library is visible to everyone with the file. A variables write changes tokens other files consume. A duplicate creates another file. None of those are implied by "look at the button."

Tier 2 for a View or Collab seat is up to 5 requests a minute. Tier 3 for that seat is up to 10 a minute. Dev and Full seats are much higher, which is how a token with a Full seat can spam a library before anyone notices. The allowlist is the brake. If the task is "describe this node," the comment method stays disabled.

Policy as code can reject a comment body, or keep the variables method denied. Do not rely on the prompt. The prompt is what asked for the comment in the first place.

Cache the node JSON you already fetched. Figma's own guidance is to batch ids and to avoid a new file read on every UI navigation. An agent loop is that navigation, automated. One nodes call per question, then stop, is the pattern that survives a View seat.

Read 1:2. Wait out a 429 for the number of seconds in Retry-After. Turn on a POST only when the task is explicitly a comment, a duplicate, or a variable change, and only on a file whose plan you have checked against the Tier 1 table.

Related reading

• A security checklist before company data. A shared library is company data with a wide audience.
• API governance tools for AI agents. How an allowlist stays smaller than the downloaded Figma bundle.
• Human approval for a tool call. A hold before a variables write, on Business and Enterprise.
• Log every API call an agent makes. How you see a View seat burning its monthly Tier 1 budget.

FAQ

Can the Figma REST API move a layer or rewrite a component?

Not as a generic node update. Reads are GET file and GET file nodes. The REST writes in Figma's rate-limit tiers include comments, duplicating a file, and posting variables. Changing geometry inside a file is plugin-API work.

Why did a Full seat still get a monthly cap?

The cap follows the file's plan and the seat, not the best plan on the account. A personal access token reading a Starter or View-scoped file uses that file's limit. Figma's table shows up to 20 Tier 1 requests a month for View and Collab seats, and says the live number can be lower.

Does fetching three nodes cost three requests?

Pass the ids in one ids query on GET file nodes. That is one request. Three separate file calls are three requests, and on a View seat they are three hits on a monthly counter.

Should the agent retry a 429 immediately?

No. Read Retry-After and wait that many seconds. Immediate retries spend the same budget and keep the bucket full. Figma uses a leaky bucket and returns 429 when the bucket cannot take the call.