Update Variables

Modify existing variables, modes, or collections. Use this to sync updated design tokens from your codebase back to Figma.

PUT 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 containing the variables to update.

Request Body

The request body is a JSON object with optional arrays for each resource type. Each item must have "action": "UPDATE" and a valid permanent ID.

Field	Type	Required	Description
`variableCollections`	`array`	No	Collections to update
`variableModes`	`array`	No	Modes to update
`variables`	`array`	No	Variables to update

Show variables item fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | action | string | Yes | Must be "UPDATE" | | id | string | Yes | The permanent Figma variable ID | | name | string | No | New variable name | | description | string | No | New description | | variableModeValues | array | No | Values to set for specific modes |

Show variableModeValues item fields

| Field | Type | Required | Description | |-------|------|----------|-------------| | modeId | string | Yes | The mode ID to set the value for | | value | any | Yes | The value. Type depends on resolvedType: COLOR = {r,g,b,a}, FLOAT = number, STRING = string, BOOLEAN = boolean |

Example Request

curl -X PUT "https://api.figma.com/v1/files/YOUR_FILE_KEY/variables" \
  -H "X-Figma-Token: YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": [
      {
        "action": "UPDATE",
        "id": "VariableID:1:1",
        "name": "brand/primary-updated",
        "variableModeValues": [
          {
            "modeId": "1:0",
            "value": { "r": 0.7, "g": 0.4, "b": 1.0, "a": 1.0 }
          }
        ]
      }
    ]
  }'

Response

Returns a 200 OK status on success with the updated variable metadata.

{
  "meta": {
    "tempIdMapping": {}
  }
}

Updating variables affects all instances where they are used across the file. Test changes in a draft file before applying them to production design systems.

You can update multiple variables in a single request by including multiple items in the variables array. This is more efficient and counts as a single API call against your rate limit.