Figma Hello World

Overview

Make your first Figma REST API call. Fetch a file's metadata and document tree, then inspect the node structure that represents every layer and object in a Figma design.

Prerequisites

• Completed figma-install-auth setup
• A Figma file key (from the URL: figma.com/design/<FILE_KEY>/...)
• FIGMA_PAT environment variable set

Instructions

Step 1: Fetch a File

bash
# Get the full document JSON for a file
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" | jq '{
    name: .name,
    lastModified: .lastModified,
    version: .version,
    pages: [.document.children[] | .name]
  }'

Expected output:

json
{
  "name": "My Design File",
  "lastModified": "2025-03-15T10:30:00Z",
  "version": "1234567890",
  "pages": ["Page 1", "Components", "Tokens"]
}

Step 2: Understand the Node Tree

Every Figma file is a tree of typed nodes:

DOCUMENT (root)
├── CANVAS (page)
│   ├── FRAME (container / auto-layout)
│   │   ├── TEXT
│   │   ├── RECTANGLE
│   │   └── INSTANCE (component instance)
│   ├── GROUP
│   │   └── VECTOR
│   ├── COMPONENT (reusable master)
│   └── SECTION

Key node types: DOCUMENT, CANVAS, FRAME, GROUP, RECTANGLE, ELLIPSE, TEXT, VECTOR, COMPONENT, COMPONENT_SET, INSTANCE, LINE, SECTION, BOOLEAN_OPERATION.

Step 3: TypeScript Hello World

typescript
// hello-figma.ts
const PAT = process.env.FIGMA_PAT!;
const FILE_KEY = process.env.FIGMA_FILE_KEY!;

interface FigmaNode {
  id: string;
  name: string;
  type: string;
  children?: FigmaNode[];
}

interface FigmaFileResponse {
  name: string;
  lastModified: string;
  version: string;
  document: FigmaNode;
  components: Record<string, { key: string; name: string; description: string }>;
  styles: Record<string, { key: string; name: string; style_type: string }>;
}

async function main() {
  const res = await fetch(
    `https://api.figma.com/v1/files/${FILE_KEY}`,
    { headers: { 'X-Figma-Token': PAT } }
  );

  if (!res.ok) {
    throw new Error(`Figma API error: ${res.status} ${res.statusText}`);
  }

  const file: FigmaFileResponse = await res.json();

  console.log(`File: ${file.name}`);
  console.log(`Last modified: ${file.lastModified}`);
  console.log(`Components: ${Object.keys(file.components).length}`);
  console.log(`Styles: ${Object.keys(file.styles).length}`);

  // Walk the first page and list top-level frames
  const firstPage = file.document.children?.[0];
  if (firstPage) {
    console.log(`\nPage: ${firstPage.name}`);
    for (const child of firstPage.children ?? []) {
      console.log(`  ${child.type}: ${child.name} (${child.id})`);
    }
  }
}

main().catch(console.error);

Step 4: Fetch Specific Nodes

typescript
// Fetch only specific nodes by ID (faster for large files)
async function fetchNodes(fileKey: string, nodeIds: string[]) {
  const ids = nodeIds.join(',');
  const res = await fetch(
    `https://api.figma.com/v1/files/${fileKey}/nodes?ids=${ids}`,
    { headers: { 'X-Figma-Token': PAT } }
  );
  const data = await res.json();
  // data.nodes is a map: { "nodeId": { document: {...}, components: {...} } }
  return data.nodes;
}

// Node IDs use the format "pageId:frameId" (e.g., "0:1", "123:456")
const nodes = await fetchNodes(FILE_KEY, ['0:1', '2:3']);

Output

• File metadata (name, version, last modified)
• Page names listed from the document tree
• Top-level frames with node IDs and types
• Component and style counts

Error Handling

| Error | Status | Cause | Solution | |-------|--------|-------|----------| | Not found | 404 | Invalid file key | Verify the key from the Figma URL | | Forbidden | 403 | No access to file | Check token scopes and file permissions | | Rate limited | 429 | Too many requests | Honor Retry-After header | | Empty document | 200 | File has no pages | Check if file was recently created |

Examples

Quick Node Counter

bash
# Count total nodes in a file
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
  | jq '[.. | .id? // empty] | length'

Get File Thumbnail

bash
curl -s -H "X-Figma-Token: ${FIGMA_PAT}" \
  "https://api.figma.com/v1/files/${FIGMA_FILE_KEY}" \
  | jq -r '.thumbnailUrl'

Resources

• Figma REST API Introduction
• File Endpoints Reference
• Node Types Reference

Next Steps

Proceed to figma-local-dev-loop for setting up a development workflow.