A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Figma API is how an app or AI agent works with a Figma workspace: reading a file's design and nodes, rendering nodes as images, posting and reading comments, and listing the projects, components, and styles a team has published. Access is granted through a personal access token or an OAuth 2.0 grant carrying granular scopes, each naming an area and whether a call can read or write, and an agent is limited to the files and teams that token can reach. Figma can also push events to a receiver when a file changes, a version is saved, or a comment is posted.
How an app or AI agent connects to Figma determines what it can reach. There is a route for reading and writing through the REST API, a route for receiving events, and a hosted server that exposes Figma tools to agents, and each is governed by the token behind it and the permissions that token carries.
The REST API answers at https://api.figma.com and returns JSON. A call authenticates with a personal or plan access token in the X-Figma-Token header, or with an OAuth 2.0 bearer token. Figma for Government uses a separate host at https://api.figma-gov.com.
Figma POSTs an event to a receiver URL when a chosen event happens on a file, project, or team. The passcode set when the webhook is created is included so the receiver can confirm the request came from Figma. Events include FILE_UPDATE, FILE_VERSION_UPDATE, FILE_DELETE, FILE_COMMENT, LIBRARY_PUBLISH, and DEV_MODE_STATUS_UPDATE.
Figma's first-party remote Model Context Protocol server at https://mcp.figma.com/mcp lets an agent pull design context, like variables, components, and layout, and generate code from selected frames, and it can create and modify Figma content. It authenticates through Figma's OAuth flow. The write-to-canvas capability is in beta.
A personal access token acts as the user who created it and is sent in the X-Figma-Token header. Scopes are chosen when the token is generated. Since April 2025 a personal access token can be set to expire in at most 90 days.
OAuth 2.0 uses the authorization-code flow so an app acts on behalf of a user who grants a chosen set of scopes. The access token is sent as a bearer token, and a refresh token keeps it current. This is the route for an app that connects on behalf of many users.
The Figma API is split into areas an agent can act on, like file contents, rendered images, comments, projects, published components and styles, and variables. Each area has its own methods and its own permission, and some reach far more than others.
Read a file's full JSON, read specific nodes, render nodes as images, get download links for image fills, and read file metadata.
List comments on a file, post a new comment, delete a comment, and add or remove reactions.
List the saved versions in a file's history.
List the projects in a team and the files in a project.
Read published components, component sets, and styles by team, by file, or by key.
Read the profile of the authenticated user.
List, read, create, update, and delete webhooks that deliver file and project events.
Read local and published variables, and create, update, or delete variables and collections. Enterprise only.
Read the dev resources linked to a file, and add, update, or remove them.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Files & imagesRead a file's full JSON, read specific nodes, render nodes as images, get download links for image fills, and read file metadata.5 | ||||||
| GET | /v1/files/:file_key | Get a file's full document as a JSON object, including its node tree and component metadata. | read | file_content:read | Current | |
A Tier 1 endpoint. The deprecated files:read scope also satisfies it. The depth and ids parameters keep the response small. Acts onfile Permission (capability) file_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/nodes | Get the JSON for specific nodes in a file, referenced by their node ids. | read | file_content:read | Current | |
A Tier 1 endpoint. Reads only the requested nodes rather than the whole document. Acts onfile Permission (capability) file_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/images/:file_key | Render one or more nodes in a file as images and return download URLs. | read | file_content:read | Current | |
A Tier 1 endpoint. Output format and scale are set by query parameters; large renders can time out with a 500. Acts onimage Permission (capability) file_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/images | Get download links for all images used as image fills in a file. | read | file_metadata:read | Current | |
Returns the original uploaded images, not rendered nodes. Uses the file_metadata:read scope. Acts onimage fill Permission (capability) file_metadata:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/meta | Get a file's metadata, such as name, last touched time, and editor type, without the file contents. | read | file_metadata:read | New | |
Added in April 2025. Returns metadata only, so it does not need file_content:read. Acts onfile Permission (capability) file_metadata:readVersionIntroduced 2025-04-29 Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsList comments on a file, post a new comment, delete a comment, and add or remove reactions.6 | ||||||
| GET | /v1/files/:file_key/comments | List the comments left on a file. | read | file_comments:read | Current | |
The as_md parameter returns comment bodies as markdown. The deprecated files:read scope also satisfies it. Acts oncomment Permission (capability) file_comments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/files/:file_key/comments | Post a new comment on a file, optionally pinned to a node or canvas position. | write | file_comments:write | Current | |
A write that posts a comment visible to collaborators. Fires the FILE_COMMENT webhook event. Acts oncomment Permission (capability) file_comments:writeVersionAvailable since the API’s base version Webhook event file_commentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/files/:file_key/comments/:comment_id | Delete a comment from a file. | write | file_comments:write | Current | |
Only the comment's author can delete it. Acts oncomment Permission (capability) file_comments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/comments/:comment_id/reactions | List the reactions on a comment. | read | file_comments:read | Current | |
Cursor-paginated through the cursor query parameter. Acts onreaction Permission (capability) file_comments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/files/:file_key/comments/:comment_id/reactions | Add an emoji reaction to a comment. | write | file_comments:write | Current | |
The emoji is given as a shortcode in the request body. Acts onreaction Permission (capability) file_comments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/files/:file_key/comments/:comment_id/reactions | Remove an emoji reaction from a comment. | write | file_comments:write | Current | |
The emoji to remove is given in the emoji query parameter. Acts onreaction Permission (capability) file_comments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Version historyList the saved versions in a file's history.1 | ||||||
| GET | /v1/files/:file_key/versions | List the saved versions in a file's history, newest first. | read | file_versions:read | Current | |
A Tier 2 endpoint. Paginated through before and after parameters with a page_size up to 50. Acts onversion Permission (capability) file_versions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Projects & teamsList the projects in a team and the files in a project.2 | ||||||
| GET | /v1/teams/:team_id/projects | List the projects in a team. | read | projects:read | Current | |
New app access to the projects endpoints requires Figma approval as of April 2025. Acts onproject Permission (capability) projects:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/projects/:project_id/files | List the files in a project. | read | projects:read | Current | |
The branch_data parameter includes branch metadata for each file. Acts onfile Permission (capability) projects:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Components & stylesRead published components, component sets, and styles by team, by file, or by key.4 | ||||||
| GET | /v1/teams/:team_id/components | List the components published to a team's library. | read | team_library_content:read | Current | |
Returns only assets published to the team library. The page_size parameter is capped at 1000 as of July 2025. Acts oncomponent Permission (capability) team_library_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/components | List the published components in a file. | read | library_content:read | Current | |
Scoped to one file rather than a whole team library. Acts oncomponent Permission (capability) library_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/component_sets | List the published component sets in a file. | read | library_content:read | Current | |
A component set groups the variants of one component. Acts oncomponent set Permission (capability) library_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/files/:file_key/styles | List the published styles in a file, such as colors, text, and effects. | read | library_content:read | Current | |
Styles cover fill, text, effect, and grid definitions. Acts onstyle Permission (capability) library_content:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersRead the profile of the authenticated user.1 | ||||||
| GET | /v1/me | Get the profile of the authenticated user. | read | current_user:read | Current | |
Returns the calling user's name, email, and profile image. A Tier 3 endpoint. Acts onuser Permission (capability) current_user:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList, read, create, update, and delete webhooks that deliver file and project events.4 | ||||||
| GET | /v2/webhooks | List the webhooks for a context or for everything in a plan that the token can reach. | read | webhooks:read | Current | |
Webhooks use the v2 namespace. The earlier team-scoped list endpoint is deprecated. Acts onwebhook Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/webhooks | Create a webhook that delivers a chosen event for a file, project, or team to a receiver URL. | write | webhooks:write | Current | |
Since May 2025 a webhook can attach to a file or project, not only a team. Creating one fires a PING event. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook event pingRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/webhooks/:webhook_id | Update a webhook's event, receiver URL, status, or other settings. | write | webhooks:write | Current | |
A write that changes where and when events are delivered. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/webhooks/:webhook_id | Delete a webhook so it stops delivering events. | write | webhooks:write | Current | |
Irreversible; the webhook must be recreated to resume. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
VariablesRead local and published variables, and create, update, or delete variables and collections. Enterprise only.2 | ||||||
| GET | /v1/files/:file_key/variables/local | Read the local variables and collections defined in a file. | read | file_variables:read | Current | |
Available only to members of Enterprise organizations. Acts onvariable Permission (capability) file_variables:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/files/:file_key/variables | Create, update, or delete variables and collections in a file in a single call. | write | file_variables:write | Current | |
Enterprise only. One request adds, changes, and removes variables, and returns a map from temporary ids to real ids. Acts onvariable Permission (capability) file_variables:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Dev resourcesRead the dev resources linked to a file, and add, update, or remove them.3 | ||||||
| GET | /v1/files/:file_key/dev_resources | List the dev resources linked to nodes in a file. | read | file_dev_resources:read | Current | |
Dev resources are external links attached to nodes for developers. Acts ondev resource Permission (capability) file_dev_resources:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/dev_resources | Add one or more dev resources to nodes across files. | write | file_dev_resources:write | Current | |
Each resource links a node to an external URL. Acts ondev resource Permission (capability) file_dev_resources:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/files/:file_key/dev_resources/:dev_resource_id | Delete a dev resource from a file. | write | file_dev_resources:write | Current | |
Removes a single linked resource by its id. Acts ondev resource Permission (capability) file_dev_resources:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Figma can notify an app or AI agent when something happens in a file, project, or team, like a new version being saved or a comment being posted, instead of the app repeatedly asking. Figma posts the event to a receiver URL registered for the chosen event type.
| Event | What it signals | Triggered by |
|---|---|---|
PING | Fires once when a webhook is created, to confirm the receiver URL is reachable. | /v2/webhooks |
FILE_UPDATE | Fires when a file's contents change, at most once every 30 minutes per file while it is being edited. | In-app only |
FILE_VERSION_UPDATE | Fires when a named version is added to a file's version history. | In-app only |
FILE_DELETE | Fires when a file is deleted, sent to webhooks watching the file or its containing context. | In-app only |
FILE_COMMENT | Fires when a comment is posted on a file. | /v1/files/:file_key/comments |
LIBRARY_PUBLISH | Fires when components or styles are published from a library file. | In-app only |
DEV_MODE_STATUS_UPDATE | Fires when a node's Dev Mode status changes, such as being marked ready for development. Added in May 2025. | In-app only |
Figma limits how fast an app or AI agent can call by sorting each endpoint into one of three cost tiers, then setting a per-minute quota for that tier based on the calling user's seat and the team's plan.
Figma sorts every endpoint into one of three cost tiers, then sets a per-minute quota for that tier from the calling user's seat type and the team's plan. Tier 1 covers the heaviest file reads, like getting a file, its nodes, or rendered images, and allows around 10 requests per minute on Starter up to 20 per minute on Organization and Enterprise for a Dev or Full seat. Tier 2 covers comments, version history, webhooks, and variables, allowing around 25 per minute on Starter up to 100 per minute on Organization and Enterprise. Tier 3 covers lighter calls like components, the current user, and activity logs, allowing around 50 per minute on Starter up to 150 per minute on Organization and Enterprise. A view or collaborate seat gets far smaller allowances. Exceeding a tier returns HTTP 429 with a Retry-After header. These tiers and limits took effect on 17 November 2025.
Pagination depends on the endpoint. Version history uses before and after cursors with a page_size up to 50. Comment reactions and team library listings use a cursor parameter, and team component and style listings cap page_size at 1000. The file endpoints return the whole requested document or node set in one response, narrowed by the ids and depth parameters rather than paged.
There is no single documented payload size limit. A request for a very large file can be rejected with a message to filter by the ids and depth parameters, and a large image render can time out with a 500. The image endpoints return download URLs rather than embedding image bytes in the response.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | A parameter is invalid or malformed, or the request body failed validation. A request for a very large file can also be rejected here with a message to filter by ids and depth. | Correct the parameters, and narrow a large file request with the ids and depth query parameters. |
| 403 | Forbidden | The token is valid but not permitted: it lacks the scope the request needs, the user cannot see the resource, or the request was not made over HTTPS. | Grant the missing scope, confirm the user has access, and call over HTTPS. |
| 404 | Not Found | The requested file or resource does not exist, or is not visible to the token. | Confirm the file key or resource id and that the token can reach it. |
| 429 | Too Many Requests | A rate limit was exceeded for the endpoint's tier. The response carries a Retry-After header and X-Figma-Rate-Limit-Type and X-Figma-Plan-Tier headers. | Wait the seconds in the Retry-After header before retrying. |
| 500 | Internal Server Error | An error on Figma's side. A large image render can time out here. | Retry, and for renders request fewer or smaller nodes. |
Figma runs a single, continuously updated REST API with no dated version to pin. Notable changes ship through release notes, and the OpenAPI specification that describes the whole surface is published and kept current.
Figma runs a single, continuously updated REST API with no dated version to pin and no version header to send. Notable changes ship through dated release notes, and an open OpenAPI specification in the figma/rest-api-spec repository describes the whole surface and is kept current. The list below is a timeline of notable dated changes, newest first.
Documented extended collections in the variables endpoints, letting a collection define variants with custom override values. Released 18 November 2025.
Announced a new OAuth app publishing requirement with a 17 November 2025 deadline, consolidated the developer documentation, and adjusted the rate limits that took effect 17 November 2025. Released 23 September 2025.
Webhooks v2 gained the ability to attach to files and projects, not only teams, a new GET endpoint to list them, and a DEV_MODE_STATUS_UPDATE event. Released 28 May 2025.
Added the GET file metadata endpoint, which returns file information without the file content under the file_metadata:read scope, and around the same time introduced the granular REST API scopes that deprecate files:read, and capped personal access tokens at a 90-day expiry. Released through late April 2025.
Figma published an open OpenAPI specification and generated TypeScript types in the figma/rest-api-spec repository, giving a canonical machine-readable description of the whole REST API. Released 14 February 2024.
There is no version header to send; the API is a single, continuously updated surface.
Figma API changelog ↗Bollard AI sits between a team's AI agents and Figma. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.