Create Variables

Create new variables and/or variable collections in a file. This is the primary endpoint for syncing design tokens from code to Figma.

POST https://api.figma.com/v1/files/:file_key/variables

Authentication

Requires a valid access token with file_content:write scope. Pass via X-Figma-Token header (personal access token) or Authorization: Bearer header (OAuth).

Parameters

Path parameters

The key of the file to create variables in.

Request Body

The request body is a JSON object with three optional arrays: variableCollections, variableModes, and variables. Each item must have "action": "CREATE".

Field	Type	Required	Description
`variableCollections`	`array`	No	Collections to create
`variableModes`	`array`	No	Modes to create within collections
`variables`	`array`	No	Variables to create within collections

Show variableCollections item fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | action | string | Yes | Must be "CREATE" | | id | string | Yes | A temporary ID (e.g., temp_collection_1). Replaced by a permanent ID in the response. | | name | string | Yes | Collection name | | initialModeId | string | Yes | Temporary ID of the initial mode |

Show variableModes item fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | action | string | Yes | Must be "CREATE" | | id | string | Yes | A temporary mode ID | | name | string | Yes | Mode name (e.g., "Light", "Dark") | | variableCollectionId | string | Yes | The collection this mode belongs to (temp or permanent ID) |

Show variables item fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | action | string | Yes | Must be "CREATE" | | id | string | Yes | A temporary variable ID | | name | string | Yes | Variable name (use / for grouping) | | variableCollectionId | string | Yes | The collection this variable belongs to | | resolvedType | string | Yes | COLOR, FLOAT, STRING, or BOOLEAN | | initialModeValue | any | No | The value for the initial mode |

Example Request

curl -X POST "https://api.figma.com/v1/files/YOUR_FILE_KEY/variables" \
  -H "X-Figma-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variableCollections": [
      {
        "action": "CREATE",
        "id": "temp_collection_1",
        "name": "Spacing",
        "initialModeId": "temp_mode_1"
      }
    ],
    "variableModes": [
      {
        "action": "CREATE",
        "id": "temp_mode_1",
        "name": "Default",
        "variableCollectionId": "temp_collection_1"
      }
    ],
    "variables": [
      {
        "action": "CREATE",
        "id": "temp_var_1",
        "name": "spacing/sm",
        "variableCollectionId": "temp_collection_1",
        "resolvedType": "FLOAT",
        "initialModeValue": 8
      },
      {
        "action": "CREATE",
        "id": "temp_var_2",
        "name": "spacing/md",
        "variableCollectionId": "temp_collection_1",
        "resolvedType": "FLOAT",
        "initialModeValue": 16
      }
    ]
  }'

Response

Returns the created resources with permanent IDs mapped from temporary IDs.

{
  "meta": {
    "tempIdMapping": {
      "temp_collection_1": "VariableCollectionId:5:0",
      "temp_mode_1": "5:0",
      "temp_var_1": "VariableID:5:1",
      "temp_var_2": "VariableID:5:2"
    }
  }
}

Response Fields

Field	Type	Description
`meta.tempIdMapping`	`object`	Map of temporary IDs to permanent Figma IDs

Temporary IDs (prefixed with temp_) are replaced with permanent Figma IDs in the response. Store this mapping if your system needs to reference the created resources in future API calls.