Skip to main content

Endpoints

There are three methods provided by the Variables REST API.

GET local variables: Fetch the local variables created in the file and remote variables used in the file.

GET published variables: Fetch the variables published from this file.

POST variables: Bulk create, update, and delete local variables and variable collections.

GET local variables​

This API is available to full members of Enterprise orgs.

The GET /v1/files/:file_key/variables/local endpoint lets you enumerate local variables created in the file and remote variables used in the file. Remote variables are referenced by their subscribed_id.

As a part of the Variables related API additions, the GET /v1/files/:file_key endpoint now returns a boundVariables property, containing the variableId of the bound variable. The GET /v1/files/:file_key/variables/local endpoint can be used to get the full variable or variable collection object.

Note that GET /v1/files/:file_key/variables/published does not return modes. Instead, you will need to use the GET /v1/files/:file_key/variables/local endpoint, in the same file, to examine the mode values.

info

This is a Tier 2 endpoint and requires the file_variables:read scope.

HTTP Endpoint​

GET /v1/files/:file_key/variables/local

Return value

{
  "status": Number,
  "error": Boolean,
  "meta": {
    "variables": {
      [variableId: String]: {
        "id": String,
        "name": String,
        "key": String,
        "variableCollectionId": String,
        "resolvedType": 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR'
        "valuesByMode": {
          [modeId: String]: Boolean | Number | String | Color | VariableAlias,
        }
        "remote": Boolean,
        "description": String,
        "hiddenFromPublishing": Boolean,
        "scopes": VariableScope[],
        "codeSyntax": VariableCodeSyntax,
      }
    },
    "variableCollections": {
      [variableCollectionId: String]: {
        "id": String,
        "name": String,
        "key": String,
        "modes": [
          {
            "modeId": String,
            "name": String,
            "parentModeId": String, // Only present for extended collections, references the corresponding mode in the parent collection
          }
        ],
        "defaultModeId": String,
        "remote": Boolean,
        "hiddenFromPublishing": Boolean,
        "variableIds": String[],
        "isExtension": Boolean,
        "parentVariableCollectionId": String, // Only present when isExtension is true
        "inheritedVariableIds": String[], // Only present when isExtension is true
        "localVariableIds": String[], // Only present when isExtension is true
        "variableOverrides": { // Only present when isExtension is true
          [variableId: String]: {
            [modeId: String]: Boolean | Number | String | Color | VariableAlias
          }
        },
        "deletedButReferenced": Boolean,
      }
    }
  }
}
Path parametersDescription
file_key
String
File to get variables from. This can be a file key or branch key. Use GET /v1/files/:key with the branch_data query param to get the branch key.
Error codesDescription
400Invalid parameter. The message parameter on the response will describe the error.
401Issue with authentication. The message parameter on the response will describe the error.
403API is not available. Possible error messages are Limited by Figma plan, Incorrect account type, or Invalid scope. This could also indicate the developer / OAuth token is invalid or expired.

GET published variables​

This API is available to full members of Enterprise orgs.

The GET /v1/files/:file_key/variables/published endpoint returns the variables that are published from the given file.

The response for this endpoint contains some key differences compared to the GET /v1/files/:file_key/variables/local endpoint:

  • Each variable and variable collection contains a subscribed_id.
  • Modes are omitted for published variable collections

Published variables have two ids: an id that is assigned in the file where it is created (id), and an id that is used by subscribing files (subscribed_id). The id and key are stable over the lifetime of the variable. The subscribed_id changes every time the variable is modified and published. The same is true for variable collections.

The updatedAt fields are ISO 8601 timestamps that indicate the last time that a change to a variable was published. For variable collections, this timestamp will change any time a variable in the collection is changed.

info

This is a Tier 2 endpoint and requires the file_variables:read scope.

HTTP Endpoint​

GET /v1/files/:file_key/variables/published

Return value

{
  "status": Number,
  "error": Boolean,
  "meta": {
    "variables": {
      [variableId: String]: {
        "id": String,
        "subscribed_id": String,
        "name": String,
        "key": String,
        "variableCollectionId": String,
        "resolvedType": 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR'
        "updatedAt": String,
      }
    },
    "variableCollections": {
      [variableCollectionId: String]: {
        "id": String,
        "subscribed_id": String,
        "name": String,
        "key": String,
        "updatedAt": String,
      }
    }
  }
}
Path parametersDescription
file_key
String
File to get variables from. This must be a main file key, not a branch key, as it is not possible to publish from branches.
Error codesDescription
400Invalid parameter. The message parameter on the response will describe the error.
401Issue with authentication. The message parameter on the response will describe the error.
403API is not available. Possible error messages are Limited by Figma plan, Incorrect account type, or Invalid scope. This could also indicate the developer / OAuth token is invalid or expired.

POST variables​

This API is available to full members of Enterprise orgs. To call this API on a file, you must have edit access to the file.

The POST /v1/files/:file_key/variables endpoint lets you bulk create, update, and delete variables and variable collections.

The request body supports the following 4 top-level arrays. Changes from these arrays will be applied in the below order, and within each array, by array order.

  • variableCollections: For creating, updating, and deleting variable collections and creating extended collections.
  • variableModes: For creating, updating, and deleting modes within variable collections.
    • Each collection can have a maximum of 40 modes
    • Mode names cannot be longer than 40 characters
    • Modes cannot be created or updated in extended collections. They can be deleted if the parent mode has been deleted.
  • variables: For creating, updating, and deleting variables.
    • Each collection can have a maximum of 5000 variables
    • Variable names must be unique within a collection and cannot contain certain special characters such as .{}
    • Variables cannot be created in extended collections
  • variableModeValues: For setting a variable value under a specific mode in a root collection or creating overrides in extended collections.
    • When setting aliases, a variable cannot be aliased to itself or form an alias cycle

Temporary ids can be used to reference an object later in the same POST request body. They can be used at create time in the id property of variable collections, modes, variables, and in the initialModeId property of variable collections. They are scoped to a single request body, and must be unique within the body. The mapping of temporary ids to real ids is returned in the response.

This endpoint has the following key behaviors:

  • The request body must be 4MB or less.
  • Must include an action property for collections, modes, and variables to tell the API whether to create, update, or delete the object.
  • When creating a collection, mode, or variable, you can include a temporary id that can be referenced in dependent objects in the same request. For example, you can create a new collection with the id my_new_collection. You can then set variableCollectionId to my_new_collection in new modes or variables. Temporary ids must be unique in the request body.
  • New collections always come with one mode. You can reference this mode by setting initialModeId to a temporary id in the request body. This is useful if you want to set values for variables in the mode in the variableModeValues array.
    • The tempIdToRealId array returns a mapping of the temporary ids in the request, to the real ids of the newly created objects.
  • Extended collections: To create an extended collection, set parentVariableCollectionId to the id of the collection you want to extend. Extended collections inherit all variables and modes from the parent.
    • When creating an extended collection, you cannot use initialModeId (since modes are inherited from the parent). Instead, use initialModeIdToParentModeIdMapping to map parent mode IDs to temporary mode IDs that you can reference elsewhere in the request body.
    • Only local variable collections can be extended. Attempting to extend a remote collection will result in an error.
  • Variable overrides: The modeId in variableModeValues determines whether you update or override a variable value:
    • Using an original mode ID (e.g., 1:0) updates the value in the variable's root collection
    • Using an extended mode ID (e.g., VariableCollectionId:2:5/2:0) creates or updates an override in the specified extended collection
    • To remove an override, set the value to null in variableModeValues. This only works with extended mode IDs and will cause an error if used with an original mode ID.
  • When adding new modes or variables, default variable values will be applied, consistent with what happens in the UI.
  • Everything to be created, updated, and deleted in the request body is treated as one atomic operation. If there is any validation failure, you will get a 400 status code response, and no changes will be persisted.
  • You will not be able to update remote variables or variable collections. You can only update variables in the file where they were originally created.
warning

Warning: If a string variable is bound to a text node content in the same file, and the text node uses a shared font in the organization, that variable cannot be updated and will result in a 400 response.

The below types are accepted in the request body for this endpoint:

NameProperties

VariableCollectionChange​

An object that contains details about the desired VariableCollection change.

actionStringrequired

The action to perform for the variable collection, as a string enum.

  • CREATE
  • UPDATE
  • DELETE
idString
Required for UPDATE or DELETE, optional for CREATE. This is the id of the target Variable Collection. For CREATE, you can provide a temporary id.
nameString
Required for CREATE, optional for UPDATE. The name of the variable collection.
parentVariableCollectionIdString
Optional for CREATE. The id of the parent variable collection to extend. When set, creates an extended collection that inherits all variables and modes from the parent. Cannot be used together with initialModeId. Only local variable collections can be extended.
initialModeIdString
Optional for CREATE. The initial mode refers to the mode that is created by default. You can set a temporary id here, in order to reference this mode later in this request. Cannot be used when parentVariableCollectionId is set, as extended collections inherit modes from their parent.
initialModeIdToParentModeIdMappingMap<String, String>
Optional for CREATE when extending a collection. Maps mode IDs from the parent collection to temporary mode IDs for the new extended collection. This allows you to reference the inherited modes using temporary IDs elsewhere in the same request body. The map can be sparse and only needs to include modes you want to reference. Only valid when parentVariableCollectionId is set.
hiddenFromPublishingBoolean
Whether this variable collection is hidden when publishing the current file as a library.

VariableModeChange​

An object that contains details about the desired variable mode change.

actionStringrequired

The action to perform for the variable mode, as a string enum.

  • CREATE
  • UPDATE
  • DELETE
idString
Required for UPDATE or DELETE, optional for CREATE. This is the id of the target variable mode. For CREATE, you can provide a temporary id.
nameString
Required for CREATE, optional for UPDATE`. The name of the mode.
variableCollectionIdString
Required. The variable collection that contains or will contain the mode. You can use the temporary id of a variable collection.

VariableChange​

An object that represents the action you want to take with a variable.

actionStringrequired

The action to perform for the variable, as a string enum.

  • CREATE
  • UPDATE
  • DELETE
idString
Required for UPDATE or DELETE, optional for CREATE. This is the id of the target variable. For CREATE, you can provide a temporary id.
nameString
Required for CREATE, optional for UPDATE. The name of the variable.</Property> <Property name="variableCollectionId" type="String">Required for CREATE`. The variable collection that contains or will contain the variable. You can use the temporary id of a variable collection.
resolvedTypeString

Required for CREATE. The resolved type of the variable, as a string enum.

  • BOOLEAN
  • FLOAT
  • STRING
  • COLOR
descriptionString
Description of this variable. Optional.
hiddenFromPublishingBoolean
Whether this variable is hidden when publishing the current file as a library.
scopesVariableScope[]

An array of scopes in the UI where this variable is shown. Setting this property will show/hide this variable in the variable picker UI for different fields.

Setting scopes for a variable does not prevent that variable from being bound in other scopes (for example, via the Plugin API). This only limits the variables that are shown in pickers within the Figma UI.

codeSyntaxVariableCodeSyntax
Code syntax definitions for this variable. Code syntax allows you to represent variables in code using platform-specific names, and will appear in Dev Mode's code snippets when inspecting elements using the variable.

VariableModeValue​

An object that represents a value for a given mode of a variable. The modeId determines whether this operation updates the original variable value or creates an override in an extended collection.

variableIdStringrequired
The target variable. You can use the temporary id of a variable.
modeIdStringrequired

Must correspond to a mode in the variable collection that contains the target variable or a mode in an extended collection whose root contains the target variable. The mode ID format determines the operation:

  • Original mode ID (e.g., 1:0): Updates the value in the variable's root collection
  • Extended mode ID (e.g., VariableCollectionId:2:5/2:0): Creates or updates an override in the specified extended collection
valueBoolean | Number | String | Color | VariableAlias | nullrequired

The value for the variable. The value must match the variable's type. If setting to a variable alias, the alias must resolve to this type.

Special behavior for extended collections: Set to null to remove an override in an extended collection. The variable value will revert to the inherited value from the parent collection. Setting null is only valid when using an extended mode ID. Using null with an original mode ID will result in an error.

info

This is a Tier 3 endpoint and requires the file_variables:write scope.

HTTP Endpoint​

POST /v1/files/:file_key/variables

Return value

{
  "status": Number,
  "error": Boolean,
  "meta": {
    "tempIdToRealId": {
      [temporaryId: String]: String
    }
  }
}
Path parametersDescription
file_key
String
File to get variables from. This can be a file key or branch key. Use GET /v1/files/:key with the branch_data query param to get the branch key.
Body parametersDescription
variableCollections
VariableCollectionChange[]optional
For creating, updating, and deleting variable collections.
variableModes
VariableModeChange[]optional
For creating, updating, and deleting modes within variable collections.
variables
VariableChange[]optional
For creating, updating, and deleting variables.
variableModeValues
VariableModeValue[]optional
For setting or overridding a variable value under a specific mode.
Error codesDescription
400Invalid parameter. The message parameter on the response will describe the error.
403API is not available. Possible error messages are Limited by Figma plan, Incorrect account type, Invalid scope, Insufficient file permissions, or API only available for design files. This could also indicate the developer / OAuth token is invalid or expired.
404The specified file was not found.
413Request payload too large. The max allowed body size is 4MB.

Examples​

The following examples are request bodies for the POST variables endpoint.

To create a new variable collection:

{
  "variableCollections": [
    {
      "action": "CREATE",
      "name": "Example variable collection"
    }
  ]
}

To create a variable in an existing variable collection:

{
  "variables": [
    {
      "action": "CREATE",
      "name": "New Variable",
      "variableCollectionId": "VariableCollectionId:1:2",
      "resolvedType": "FLOAT"
    }
  ]
}

To create a variable mode in an existing variable collection:

{
  "variableModes": [
    {
      "action": "CREATE",
      "name": "New Mode",
      "variableCollectionId": "VariableCollectionId:1:2"
    }
  ]
}

To set a value for an existing variable:

{
  "variableModeValues": [
    {
      "variableId": "VariableID:2:3",
      "modeId": "1:0",
      "value": { "r": 1, "g": 0, "b": 0 }
    }
  ]
}

To set a variable alias to an existing variable:

{
  "variableModeValues": [
    {
      "variableId": "VariableID:2:4",
      "modeId": "1:0",
      "value": { "type": "VARIABLE_ALIAS", "id": "VariableID:1:3" }
    }
  ]
}

To rename an existing variable:

{
  "variables": [
    {
      "action": "UPDATE",
      "id": "VariableID:1:3",
      "name": "New Variable"
    }
  ]
}

To set code syntax for a variable:

{
  "variables": [
    {
      "action": "UPDATE",
      "id": "VariableID:1:3",
      "codeSyntax": { "WEB": "variable-name", "ANDROID": "variableName", "iOS": "variableName" }
    }
  ]
}

To rename an existing variable mode:

{
  "variableModes": [
    {
      "action": "UPDATE",
      "id": "1:0",
      "name": "New Mode Name",
      "variableCollectionId": "VariableCollectionId:1:2"
    }
  ]
}

To create a new variable collection that contains a variable:

{
  "variableCollections": [
    {
      "action": "CREATE",
      "id": "my_variable_collection", // sets a temporary id for the variable collection
      "name": "New Variable Collection",
      "initialModeId": "my_mode" // sets a temporary id for the initial variable mode
    }
  ],
  "variableModes": [
    {
      "action": "UPDATE",
      "id": "my_mode",
      "name": "My Mode", // rename the initial variable mode
      "variableCollectionId": "my_variable_collection" // uses the temporary id of the variable collection
    }
  ],
  "variables": [
    {
      "action": "CREATE",
      "id": "my_variable",
      "name": "float variable",
      "resolvedType": "FLOAT",
      "variableCollectionId": "my_variable_collection" // uses the temporary id of the variable collection
    }
  ],
  "variableModeValues": [
    {
      "variableId": "my_variable", // uses the temporary id of the variable
      "modeId": "my_mode", // uses the temporary id of the variable mode
      "value": 100
    }
  ]
}

To delete a variable mode:

{
  "variableModes": [
    {
      "action": "DELETE",
      "id": "2:0",
      "variableCollectionId": "VariableCollectionId:2:3"
    }
  ]
}

To create an extended collection:

{
  "variableCollections": [
    {
      "action": "CREATE",
      "name": "Dark Theme",
      "parentVariableCollectionId": "VariableCollectionId:1:2"
    }
  ]
}

To create an extended collection and reference its inherited modes using temporary IDs:

{
  "variableCollections": [
    {
      "action": "CREATE",
      "id": "my_extended_collection",
      "name": "Dark Theme",
      "parentVariableCollectionId": "VariableCollectionId:1:2",
      "initialModeIdToParentModeIdMapping": {
        "1:0": "temp_light_mode",
        "1:1": "temp_dark_mode"
      }
    }
  ],
  "variableModeValues": [
    {
      "variableId": "VariableID:1:3",
      "modeId": "temp_dark_mode", // references the inherited mode using temporary ID
      "value": { "r": 0.1, "g": 0.1, "b": 0.1, "a": 1 }
    }
  ]
}

To override a variable value in an extended collection:

{
  "variableModeValues": [
    {
      "variableId": "VariableID:1:3",
      "modeId": "VariableCollectionId:2:5/1:0", // extended mode ID creates an override
      "value": { "r": 0.2, "g": 0.2, "b": 0.2, "a": 1 }
    }
  ]
}

To remove an override in an extended collection:

{
  "variableModeValues": [
    {
      "variableId": "VariableID:1:3",
      "modeId": "VariableCollectionId:2:5/1:0", // extended mode ID
      "value": null // removes the override, falls back to parent value
    }
  ]
}

To demonstrate the difference between updating in root vs overriding in extended collection:

{
  "variableModeValues": [
    {
      "variableId": "VariableID:1:3",
      "modeId": "1:0", // original mode ID updates the root collection value
      "value": { "r": 1, "g": 1, "b": 1, "a": 1 }
    },
    {
      "variableId": "VariableID:1:3",
      "modeId": "VariableCollectionId:2:5/1:0", // extended mode ID creates override in extended collection
      "value": { "r": 0, "g": 0, "b": 0, "a": 1 }
    }
  ]
}