Figma

Figma

Figma content is addressed by file, team, or global library key.

Identifiers

• file_key — the segment after the design or file segment in a Figma share URL (figma.com/design/FILE_KEY/Name). The credential carries an optional default; pass file_key explicitly to target a different file.
• team_id — the numeric segment in a team URL (figma.com/files/team/TEAM_ID/). The credential carries an optional default.
• node_id — page_id:index (e.g. 1:2); discoverable from the file tree.
• component_key / component_set_key / style_key — global keys used to fetch a single library entity directly.

Hierarchy

Team → Project → File → Page → Frame → Node. Components, component sets, styles, and variables are scoped to a file (the local view) and may also be published to the team library, which is what other files consume.

Operational order

1. Validate the credential with the current-user read.
2. List team styles to discover library file_keys when you don't already have one.
3. Read a file's metadata to confirm access cheaply before pulling the full document tree (which can be many MB).
4. Read the file (full tree) or pass ids= to read only those nodes — same response shape, partial reads are dramatically cheaper for large design systems.
5. Render images for specific node ids when you need raster / vector exports.

Read consolidation

• Components / component sets / styles: one read tool per family. Pass the global key (component_key / component_set_key / style_key) for single fetch; otherwise scope to file_key (file-local) or team_id (published library). file_key wins when both are supplied. Team scope supports cursor pagination via page_size + before / after.
• Files: pass ids= (comma-separated node ids) to switch from "full file tree" to "deep node read" — the response shape matches.
• Library analytics: a single read tool dispatches on kind (component / style / variable) and mode (actions time series / usages current map).
• Webhooks: pass webhook_id for single, otherwise list scoped to team_id.
• Dev resources: list scoped to a file_key, optionally narrowed to one node_id.

Write consolidation

• upsert_* tools dispatch on whether an id-like argument is present:
  • Webhooks: omit webhook_id to create, pass it to update. Use status='PAUSED' to temporarily stop delivery without deleting.
  • Dev resources: bulk-only (max 100 per call). Items without id go in the create batch, items with id go in the update batch. The response merges both branches and surfaces per-item errors.
  • Variables: a single bulk envelope mutates variable collections, modes, variables, and mode values in one transaction with per-item action of CREATE / UPDATE / DELETE. Temporary client ids (tmp_…) round-trip in the response.
• Comments and comment reactions only support create + delete (no update on the API), so the write tools are named create_* / delete_* rather than upsert_*. To "edit" a comment, delete and recreate.

Rendering

• The render tool exports nodes as PNG (default), JPG, SVG, or PDF; scale runs 0.01–4 (retina = 2).
• SVG-specific knobs: svg_outline_text=true (default) converts text to vector paths for pixel parity; svg_include_id / svg_include_node_id emit attributes for round-tripping.
• The image-fills read returns the original bitmap fills baked into a file (S3 URLs valid ~30 days). The render tool produces fresh exports — distinct surfaces.

Plan-gated capabilities

The Figma REST API exposes endpoints that are gated on the workspace's Figma plan, not on the credential. These will return 403 / 400 for accounts that don't have the corresponding entitlement, even when the token is otherwise valid:

• Library analytics — Enterprise plan only. Lower plans get 403.
• Variables read / write — Enterprise organization full membership only.
• Webhook create — paid team plan; Starter / Free teams get 400 Upgrade to professional team to enable webhooks. Listing webhooks works on every plan.
• Activity logs — Enterprise + the org:activity_log_read scope.
• Dev resources — Dev Mode seat (paid).
• Payments — only the resource owner sees rows; queries against other authors' resources return 404.

Authentication shape

Two credential shapes are supported. The framework injects whichever is bound for the workspace:

• Personal Access Token → X-Figma-Token
• OAuth2 → Authorization: Bearer …

Rate limit

Figma rate-limits per token (~Tier 3 endpoints are tighter — payments, activity logs). On 429, back off; rate-limit windows reset within ~60 seconds.