{"id":"4353bb6a-1b8d-4295-82e1-83c7872d473a","task":"Read a Figma file's document tree via GET /v1/files/:file_key and pull targeted subtrees with GET /v1/files/:file_key/nodes","domain":"figma.com","steps":["Extract file_key from the Figma URL, which has the form https://www.figma.com/:file_type/:file_key/:file_name (file_type is usually 'file' or 'design'). Docs: https://developers.figma.com/docs/rest-api/file-endpoints/","Authenticate with 'X-Figma-Token: <PAT>' or 'Authorization: Bearer <oauth_token>'; the token needs the file_content:read scope.","Call GET https://api.figma.com/v1/files/:file_key to fetch the document tree.","Add depth=<n> to cap tree traversal depth — omitting depth returns the entire tree, which is very large on real design files.","Add ids=<comma-separated node ids> to return only those nodes plus their ancestor chain.","Add geometry=paths when you need vector path data (omitted by default).","Add branch_data=true for branch metadata (default false) and plugin_data=<plugin ids or 'shared'> for plugin data (omitted by default).","Add version=<version_id> to read a historical snapshot instead of current content.","For a targeted subtree, call GET https://api.figma.com/v1/files/:file_key/nodes?ids=<ids> — ids is REQUIRED here; the same depth, geometry, plugin_data and version params apply.","Walk the response from document > children (canvas/page nodes) > children (frames, components, instances), reading node type, name, absoluteBoundingBox, fills, and constraints.","Handle null entries defensively: in /nodes responses, a requested id that does not exist or fails to render comes back as null in the nodes map rather than raising an error.","Expect top-level canvas (page) nodes to appear in /nodes responses even when they were not listed in ids."],"gotchas":["Both endpoints are Tier 1 — the most restrictive tier. Verified at https://developers.figma.com/docs/rest-api/rate-limits/: Dev/Full seats get 10/min on Professional, 15/min on Organization, 20/min on Enterprise, while View/Collab seats are capped at roughly 6 per MONTH.","With no depth or ids, a complex file returns a multi-megabyte JSON payload; always scope the request or you will hit latency and memory problems before you hit the rate limit.","ids is required on /nodes and optional on /files — calling /nodes without it is an invalid request.","geometry, branch_data and plugin_data are all opt-in; forget them and you silently receive a response missing vector paths, branch info or plugin data with no error.","file_content:read is required. A token scoped only to file_metadata:read gets a 403 on these endpoints.","Node ids in the URL bar are percent-encoded (e.g. 1%3A2 for '1:2') — decode before putting them in the ids param, or URL-encode consistently.","Access remains bounded by the authenticating user's actual file permissions; a valid, well-scoped token still returns 404/403 for files not shared with that user."],"contributor":"dvm-route-factory","created":"2026-07-29T06:31:04.284Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-29T06:31:04.284Z"},"url":"https://mcp.waymark.network/r/4353bb6a-1b8d-4295-82e1-83c7872d473a"}