maddiedreese_figma/references/figma-api-reference.md

Figma API Reference

Complete reference for Figma REST API endpoints and Plugin API capabilities.

Authentication

Access Token Setup

1. Generate personal access token: Figma → Settings → Account → Personal Access Tokens
2. For team/organization usage: Create OAuth app for broader access
3. Set environment variable: FIGMA_ACCESS_TOKEN=your_token_here

API Headers

X-Figma-Token: your_access_token_here
Content-Type: application/json

REST API Endpoints

File Operations

GET /v1/files/:key

Get complete file data including document tree, components, and styles.

Parameters:

• version (optional): Specific version ID
• ids (optional): Comma-separated node IDs to limit scope
• depth (optional): How deep to traverse document tree
• geometry (optional): Set to "paths" for vector data
• plugin_data (optional): Plugin IDs to include plugin data

Response includes:

• Document tree with all nodes
• Components map with metadata
• Styles map with style definitions
• Version and file metadata

GET /v1/files/:key/nodes

Get specific nodes from a file.

Parameters:

• ids (required): Comma-separated node IDs
• version, depth, geometry, plugin_data (same as above)

GET /v1/images/:key

Export nodes as images.

Parameters:

• ids (required): Node IDs to export
• scale (optional): 1, 2, or 4 (default: 1)
• format (optional): jpg, png, svg, or pdf (default: png)
• svg_include_id (optional): Include node IDs in SVG
• svg_simplify_stroke (optional): Simplify strokes in SVG
• use_absolute_bounds (optional): Use absolute coordinates
• version (optional): Specific version to export

Returns: Map of node IDs to image URLs (URLs expire after 30 days)

GET /v1/files/:key/images

Get image fill metadata from a file.

Component Operations

GET /v1/files/:key/components

Get all components in a file.

GET /v1/components/:key

Get component metadata by component key.

GET /v1/teams/:team_id/components

Get team component library.

Parameters:

• page_size (optional): Results per page (max 1000)
• after (optional): Pagination cursor

Style Operations

GET /v1/files/:key/styles

Get all styles in a file.

GET /v1/styles/:key

Get style metadata by style key.

GET /v1/teams/:team_id/styles

Get team style library.

Project Operations

GET /v1/teams/:team_id/projects

Get projects for a team.

GET /v1/projects/:project_id/files

Get files in a project.

User Operations

GET /v1/me

Get current user information.

Rate Limits

• 1000 requests per minute per access token
• Image exports: 100 requests per minute
• Use exponential backoff for 429 responses
• Monitor X-RateLimit-* headers

Error Handling

Common HTTP Status Codes

• 400 Bad Request: Invalid parameters
• 401 Unauthorized: Invalid or missing access token
• 403 Forbidden: Insufficient permissions
• 404 Not Found: File or resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Figma server error

Error Response Format

{
  "status": 400,
  "err": "Bad request: Invalid file key"
}

Node Types

Document Structure

• DOCUMENT - Root document node
• CANVAS - Page/canvas node
• FRAME - Frame container
• GROUP - Group container
• SECTION - Section container

Shape Nodes

• RECTANGLE - Rectangle shape
• LINE - Line shape
• ELLIPSE - Ellipse shape
• POLYGON - Polygon shape
• STAR - Star shape
• VECTOR - Vector shape

Text and Components

• TEXT - Text node
• COMPONENT - Master component
• COMPONENT_SET - Component set (variants)
• INSTANCE - Component instance

Special Nodes

• BOOLEAN_OPERATION - Boolean operation result
• SLICE - Export slice
• STICKY - Sticky note (FigJam)
• CONNECTOR - Connector line (FigJam)

Plugin API Overview

The Plugin API allows creating, modifying, and analyzing design files through plugins.

Key Capabilities

• Create nodes: Generate frames, shapes, text, components
• Modify properties: Update fills, strokes, effects, layout
• Component management: Create/update components and instances
• Style operations: Create and apply text/fill/effect styles
• File operations: Navigate pages, selection, document structure

Plugin API Limitations

• Runs in browser sandbox environment
• Cannot directly access external APIs (use UI for HTTP requests)
• Limited file system access
• Must be installed/authorized by users

Common Plugin Patterns

Creating Basic Shapes

// Create rectangle
const rect = figma.createRectangle();
rect.resize(100, 100);
rect.fills = [{type: 'SOLID', color: {r: 1, g: 0, b: 0}}];

// Create text
const text = figma.createText();
await figma.loadFontAsync(text.fontName);
text.characters = "Hello World";

Working with Components

// Create component
const component = figma.createComponent();
component.name = "Button";

// Create instance
const instance = component.createInstance();

Traversing Document Tree

function traverse(node) {
  console.log(node.name, node.type);
  if ("children" in node) {
    for (const child of node.children) {
      traverse(child);
    }
  }
}

traverse(figma.root);

Best Practices

API Usage

1. Batch operations: Group multiple API calls when possible
2. Cache results: Store file data to minimize repeat requests
3. Use specific node IDs: Limit data transfer with ids parameter
4. Handle rate limits: Implement exponential backoff
5. Version awareness: Use version parameter for consistency

Image Exports

1. Choose appropriate format: PNG for complex images, SVG for icons
2. Optimize scale: Use scale=1 unless high-DPI needed
3. Batch exports: Export multiple nodes in single request
4. Cache URLs: Store image URLs but remember 30-day expiration

Plugin Development

1. Minimize processing: Keep operations fast to avoid timeouts
2. Progress feedback: Show progress for long operations
3. Error handling: Gracefully handle missing fonts, permissions
4. Memory management: Clean up large data structures
5. User consent: Request permissions appropriately

Security

1. Token protection: Never expose access tokens in client-side code
2. Scope principle: Use minimal required permissions
3. Input validation: Validate all user inputs and API responses
4. Audit logs: Track API usage for compliance

Common Use Cases

Design System Automation

• Extract design tokens (colors, typography, spacing)
• Generate code from components
• Sync design systems across files
• Audit design consistency

Asset Generation

• Export marketing assets in multiple formats
• Generate app icons and favicons
• Create social media templates
• Produce print-ready assets

Workflow Integration

• Connect designs to development tools
• Automate handoff documentation
• Version control for design files
• Collaborative review processes

Quality Assurance

• Accessibility compliance checking
• Brand guideline validation
• Consistency auditing across projects
• Performance optimization recommendations