REST API Reference

This is the complete endpoint documentation for the Handoff REST API. For an introduction to the API's architecture and authentication, please see the REST API Overview.

Tokens

GET /api/tokens.json

Returns all design tokens extracted from Figma, organized by their respective categories such as color, typography, and effects.

Response Example

example.json
json
1{
2  "timestamp": "2026-02-12T09:26:16.905Z",
3  "localStyles": {
4    "color": [
5      {
6        "id": "1203:5097",
7        "name": "Transparent",
8        "value": "rgba(255, 255, 255, 0)",
9        "sass": "$color--transparent",
10        "reference": "color--transparent",
11        "machineName": "transparent"
12      },
13      {
14        "id": "30:111",
15        "name": "Orange",
16        "group": "primary",
17        "value": "#ff4713",
18        "sass": "$color-primary-orange",
19        "reference": "color-primary-orange",
20        "machineName": "orange"
21      }
22    ],
23    "typography": [],
24    "effects": []
25  }
26}

---

Components

GET /api/components.json

Returns a list of all component definitions available in the design system, including metadata and property summaries.

Response Example

example.json
json
1[
2  {
3    "id": "about",
4    "title": "About Us",
5    "description": "A three column block layout for highlighting company values.",
6    "type": "block",
7    "group": "Content",
8    "image": "/images/components/about.png",
9    "figma": "https://www.figma.com/design/..."
10  },
11  {
12    "id": "button",
13    "title": "Button",
14    "type": "component",
15    "group": "Core"
16  }
17]

---

GET /api/component/{id}.json

Returns the full definition for a single component identified by its ID. It includes all variants, properties, and usage guidelines.

Response Example

example.json
json
1{
2  "id": "about",
3  "title": "About Us",
4  "figma": "https://www.figma.com/design/...",
5  "image": "/images/components/about.png",
6  "description": "A three column block layout...",
7  "type": "block",
8  "group": "Content",
9  "should_do": [
10    "Use images that represent company values",
11    "Keep content concise"
12  ],
13  "should_not_do": [
14    "Don't use for product pages"
15  ]
16}

---

GET /api/component/{id}/preview/{variant}.html

Returns a rendered HTML preview of a specific component variant. This is useful for embedding live previews into external documentation or internal tools.

---

Icons

GET /api/icons-sprite.svg

Returns the full SVG sprite containing all icons in the design system. You can reference individual icons in your HTML using the <use> element.

---

GET /api/icons-sprite-manifest.json

Returns a JSON manifest listing all available icon IDs and their metadata, helping you build icon pickers or dynamic icon loaders.

Response Example

example.json
json
1{
2  "arrow-left": {
3    "path": "arrow-left.svg",
4    "name": "arrow-left"
5  },
6  "arrow-right": {
7    "path": "arrow-right.svg",
8    "name": "arrow-right"
9  },
10  "chevron-down": {
11    "path": "chevron-down.svg",
12    "name": "chevron-down"
13  }
14}

---

Error Responses

The API uses standard HTTP status codes to indicate success or failure. A 200 code indicates success, while a 404 indicates a resource was not found. If you receive a 500 error, check your Handoff build logs for potential issues.