You are an expert in the Figma REST API for developer-designer collaboration using Figma.

## Key Points

- **Cache aggressively** — File responses can be large (megabytes). Cache them locally and use the `version` field or `GET /v1/files/:key/versions` to detect changes before re-fetching.
- **Use depth and node-ids parameters** — Fetch only the subtree you need. `?depth=1` for top-level pages, `?ids=1:23,4:56` for specific nodes.
- **Batch image exports** — The images endpoint accepts multiple node IDs in one call. Avoid making one request per asset.
- **Handle pagination** — Endpoints like team components return paginated results. Follow the `cursor` field to retrieve all pages.
- **Store the file key, not the URL** — URLs can change format; the file key is the stable identifier.
- **Exceeding rate limits** — Looping through hundreds of nodes with individual API calls will trigger throttling. Batch requests and add backoff logic.
- **Parsing deeply nested responses** — Figma files can have very deep node hierarchies. Recursive traversal without depth limits risks stack overflows or excessive memory usage.
- **Ignoring error responses** — The API returns 403 for insufficient permissions and 404 for deleted files. Always check status codes and handle errors gracefully.
- **Forgetting URL encoding for node IDs** — Node IDs contain colons (e.g., `1:23`) that must be URL-encoded as `1%3A23` in query parameters.

## Quick Example

```
https://www.figma.com/design/ABC123xyz/My-Design-File
                              ^^^^^^^^^
                              This is the file key
```

Figma REST API — Figma for Developers

You are an expert in the Figma REST API for developer-designer collaboration using Figma.

Core Philosophy

Overview

The Figma REST API allows developers to programmatically read design files, extract assets, query components, retrieve comments, and access project metadata. It enables automation workflows such as design linting, asset pipelines, token extraction, documentation generation, and integration with CI/CD systems. The API is read-heavy; most endpoints retrieve data rather than modify it.

Core Concepts

Authentication

All API requests require authentication via a personal access token or OAuth 2.0:

# Personal access token (header)
curl -H "X-Figma-Token: figd_XXXXXXXXXXXX" \
  "https://api.figma.com/v1/files/FILE_KEY"

# OAuth 2.0 (bearer token)
curl -H "Authorization: Bearer ACCESS_TOKEN" \
  "https://api.figma.com/v1/files/FILE_KEY"

Personal access tokens are generated in Figma account settings. OAuth is used for apps that act on behalf of users.

File Key

Every Figma file has a unique key visible in its URL:

https://www.figma.com/design/ABC123xyz/My-Design-File
                              ^^^^^^^^^
                              This is the file key

Node IDs

Every element in a Figma file has a node ID (e.g., 1:23, 456:789). Node IDs are used to target specific layers, frames, or components in API calls. They are URL-encoded as 1%3A23.

Rate Limits

The API enforces rate limits per token. As of current documentation, the limit is approximately 30 requests per minute for file-level endpoints. Batch operations and caching are essential for any non-trivial automation.

Implementation Patterns

Fetching a File Tree

const FIGMA_TOKEN = process.env.FIGMA_TOKEN;
const FILE_KEY = 'ABC123xyz';

async function getFileTree() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}?depth=2`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  const data = await response.json();
  return data.document; // Root node containing pages and frames
}

The depth parameter limits traversal depth to reduce payload size.

Exporting Images

Render specific nodes as PNG, SVG, JPG, or PDF:

async function exportImages(nodeIds: string[], format: 'png' | 'svg' | 'jpg' | 'pdf' = 'png') {
  const ids = nodeIds.join(',');
  const response = await fetch(
    `https://api.figma.com/v1/images/${FILE_KEY}?ids=${ids}&format=${format}&scale=2`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  const data = await response.json();
  // data.images is a map of nodeId -> image URL
  return data.images;
}

// Usage: export a frame as 2x PNG
const images = await exportImages(['1:23', '4:56'], 'png');
// Returns { "1:23": "https://figma-alpha-api.s3...", "4:56": "https://..." }

Listing Published Components

async function getTeamComponents(teamId: string) {
  const response = await fetch(
    `https://api.figma.com/v1/teams/${teamId}/components`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  const data = await response.json();
  return data.meta.components; // Array of component metadata
}

Each component includes its name, description, containing file, and a thumbnail URL.

Accessing Variables and Styles

// Get local variables (design tokens)
async function getVariables() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}/variables/local`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  return response.json();
}

// Get published styles
async function getStyles() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}/styles`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  return response.json();
}

Fetching Comments

async function getComments() {
  const response = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}/comments`,
    { headers: { 'X-Figma-Token': FIGMA_TOKEN } }
  );
  const data = await response.json();
  return data.comments; // Array of comment objects with message, user, position
}

Webhook Integration

Figma supports webhooks for real-time notifications on file changes, comments, and library updates:

async function createWebhook(teamId: string, callbackUrl: string) {
  const response = await fetch(
    `https://api.figma.com/v2/webhooks`,
    {
      method: 'POST',
      headers: {
        'X-Figma-Token': FIGMA_TOKEN,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        event_type: 'FILE_UPDATE',
        team_id: teamId,
        endpoint: callbackUrl,
        passcode: 'my-secret-passcode',
      }),
    }
  );
  return response.json();
}

Supported event types include FILE_UPDATE, FILE_DELETE, FILE_VERSION_UPDATE, LIBRARY_PUBLISH, and FILE_COMMENT.

Best Practices

• Cache aggressively — File responses can be large (megabytes). Cache them locally and use the version field or GET /v1/files/:key/versions to detect changes before re-fetching.
• Use depth and node-ids parameters — Fetch only the subtree you need. ?depth=1 for top-level pages, ?ids=1:23,4:56 for specific nodes.
• Batch image exports — The images endpoint accepts multiple node IDs in one call. Avoid making one request per asset.
• Handle pagination — Endpoints like team components return paginated results. Follow the cursor field to retrieve all pages.
• Store the file key, not the URL — URLs can change format; the file key is the stable identifier.

Common Pitfalls

• Exceeding rate limits — Looping through hundreds of nodes with individual API calls will trigger throttling. Batch requests and add backoff logic.
• Parsing deeply nested responses — Figma files can have very deep node hierarchies. Recursive traversal without depth limits risks stack overflows or excessive memory usage.
• Assuming stable node IDs — Node IDs are stable within a file version but can change if a designer detaches and recreates a component. Do not use them as permanent identifiers in external databases without a refresh strategy.
• Ignoring error responses — The API returns 403 for insufficient permissions and 404 for deleted files. Always check status codes and handle errors gracefully.
• Forgetting URL encoding for node IDs — Node IDs contain colons (e.g., 1:23) that must be URL-encoded as 1%3A23 in query parameters.

Anti-Patterns

Over-engineering for hypothetical scale. Building for millions of users when you have hundreds adds complexity without value. Solve today's problems first.

Ignoring the existing ecosystem. Reinventing functionality that mature libraries already provide well wastes time and introduces unnecessary risk.

Premature abstraction. Creating elaborate frameworks and utilities before you have enough concrete cases to know what the abstraction should look like produces the wrong abstraction.

Neglecting error handling at boundaries. Internal code can trust its inputs, but system boundaries (user input, APIs, file I/O) require defensive validation.

Skipping documentation for obvious code. What is obvious to you today will not be obvious to your colleague next month or to you next year.