---
title: "Create/modify/delete variables"
method: POST
path: "/v1/files/{file_key}/variables"
tags: ["Variables"]
---

# Create/modify/delete variables

`POST /v1/files/{file_key}/variables`

**This API is available to full members of Enterprise orgs with Editor seats.**

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
- **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
- **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 `.{}`
- **variableModeValues**: For setting a variable value under a specific mode.
  - 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.
- 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.

## Path parameters

- `file_key` string, required

## Request body

- object
  - `variableCollections` VariableCollectionChange[] — For creating, updating, and deleting variable collections.
    - union
      - VariableCollectionCreate — An object that contains details about creating a `VariableCollection`.
        - `action` 'CREATE', required — The action to perform for the variable collection.
        - `id` string — A temporary id for this variable collection.
        - `name` string, required — The name of this variable collection.
        - `initialModeId` string — 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.
        - `hiddenFromPublishing` boolean — Whether this variable collection is hidden when publishing the current file as a library.
        - `parentVariableCollectionId` string — The id of the parent variable collection that this variable collection is extending from.
        - `initialModeIdToParentModeIdMapping` object — Maps inherited modes from the parent variable collection to the initial mode ids on the extended variable collection.
      - VariableCollectionUpdate — An object that contains details about updating a `VariableCollection`.
        - `action` 'UPDATE', required — The action to perform for the variable collection.
        - `id` string, required — The id of the variable collection to update.
        - `name` string — The name of this variable collection.
        - `hiddenFromPublishing` boolean — Whether this variable collection is hidden when publishing the current file as a library.
      - VariableCollectionDelete — An object that contains details about deleting a `VariableCollection`.
        - `action` 'DELETE', required — The action to perform for the variable collection.
        - `id` string, required — The id of the variable collection to delete.
  - `variableModes` VariableModeChange[] — For creating, updating, and deleting modes within variable collections.
    - union
      - VariableModeCreate — An object that contains details about creating a `VariableMode`.
        - `action` 'CREATE', required — The action to perform for the variable mode.
        - `id` string — A temporary id for this variable mode.
        - `name` string, required — The name of this variable mode.
        - `variableCollectionId` string, required — The variable collection that will contain the mode. You can use the temporary id of a variable collection. New modes cannot be created on extended collections.
      - VariableModeUpdate — An object that contains details about updating a `VariableMode`.
        - `action` 'UPDATE', required — The action to perform for the variable mode.
        - `id` string, required — The id of the variable mode to update.
        - `name` string — The name of this variable mode.
        - `variableCollectionId` string, required — The variable collection that contains the mode. Modes cannot be updated on extended collections.
      - VariableModeDelete — An object that contains details about deleting a `VariableMode`.
        - `action` 'DELETE', required — The action to perform for the variable mode.
        - `id` string, required — The id of the variable mode to delete. Modes cannot be deleted on extended collections unless its parent mode has been deleted.
  - `variables` VariableChange[] — For creating, updating, and deleting variables.
    - union
      - VariableCreate — An object that contains details about creating a `Variable`.
        - `action` 'CREATE', required — The action to perform for the variable.
        - `id` string — A temporary id for this variable.
        - `name` string, required — The name of this variable.
        - `variableCollectionId` string, required — The variable collection that will contain the variable. You can use the temporary id of a variable collection.
        - `resolvedType` 'BOOLEAN' | 'FLOAT' | 'STRING' | 'COLOR', required — Defines the types of data a VariableData object can eventually equal
        - `description` string — The description of this variable.
        - `hiddenFromPublishing` boolean — Whether this variable is hidden when publishing the current file as a library.
        - `scopes` VariableScope[] — 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.
        - `codeSyntax` VariableCodeSyntax — An object containing platform-specific code syntax definitions for a variable. All platforms are optional.
          - `WEB` string
          - `ANDROID` string
          - `iOS` string
      - VariableUpdate — An object that contains details about updating a `Variable`.
        - `action` 'UPDATE', required — The action to perform for the variable.
        - `id` string, required — The id of the variable to update.
        - `name` string — The name of this variable.
        - `description` string — The description of this variable.
        - `hiddenFromPublishing` boolean — Whether this variable is hidden when publishing the current file as a library.
        - `scopes` VariableScope[] — 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.
        - `codeSyntax` VariableCodeSyntax — An object containing platform-specific code syntax definitions for a variable. All platforms are optional.
          - `WEB` string
          - `ANDROID` string
          - `iOS` string
      - VariableDelete — An object that contains details about deleting a `Variable`.
        - `action` 'DELETE', required — The action to perform for the variable.
        - `id` string, required — The id of the variable to delete.
  - `variableModeValues` VariableModeValue[] — For setting a specific value, given a variable and a mode.
    - `variableId` string, required — The target variable. You can use the temporary id of a variable.
    - `modeId` string, required — Must correspond to a mode in the variable collection that contains the target variable.
    - `value` union, required — 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. If overriding a value, the value type must match the variable's type. If removing an overridden value, the value must be `null`.
      - boolean
      - number
      - string
      - RGB — An RGB color
        - `r` number, required — Red channel value, between 0 and 1.
        - `g` number, required — Green channel value, between 0 and 1.
        - `b` number, required — Blue channel value, between 0 and 1.
      - RGBA — An RGBA color
        - `r` number, required — Red channel value, between 0 and 1.
        - `g` number, required — Green channel value, between 0 and 1.
        - `b` number, required — Blue channel value, between 0 and 1.
        - `a` number, required — Alpha channel value, between 0 and 1.
      - VariableAlias — Contains a variable alias
        - `type` 'VARIABLE_ALIAS', required
        - `id` string, required — The id of the variable that the current variable is aliased to. This variable can be a local or remote variable, and both can be retrieved via the GET /v1/files/:file_key/variables/local endpoint.

## Response `200`

Response from the POST /v1/files/{file_key}/variables endpoint.

- object
  - `status` 200, required — The response status code.
  - `error` false, required — For successful requests, this value is always `false`.
  - `meta` object, required
    - `tempIdToRealId` object, required — A map of temporary ids in the request to the real ids of the newly created objects

## Other responses

- `400` — Bad request. Parameters are invalid or malformed. Please check the input formats. This error can also happen if the requested resources are too large to complete the request, which results in a timeout. Please reduce the number and size of objects requested.
- `401` — Token is missing or incorrect.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource, or may need an account of some sort.
- `404` — The requested file or resource was not found.
- `429` — In some cases API requests may be throttled or rate limited. Please wait a while before attempting the request again (typically a minute).
- `500` — An internal server error occurred.

## Changes

- **2025-12-17** `0ad28e30d9e1` — 3 info
  - added the new optional request property `variableCollections/items/oneOf[#/components/schemas/VariableCollectionCreate]/initialModeIdToParentModeIdMapping`
  - added the new optional request property `variableCollections/items/oneOf[#/components/schemas/VariableCollectionCreate]/parentVariableCollectionId`
  - added `subschema #7` to the `variableModeValues/items/value` request property `oneOf` list
- **2025-03-27** `7da6faa8fe1b` — 2 info
  - added the new `FONT_VARIATIONS` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableCreate]/scopes/items/`
  - added the new `FONT_VARIATIONS` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableUpdate]/scopes/items/`
- **2024-05-29** `298e6853a42c` — 16 info
  - added the new `FONT_FAMILY` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableCreate]/scopes/items/`
  - added the new `FONT_FAMILY` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableUpdate]/scopes/items/`
  - added the new `FONT_SIZE` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableCreate]/scopes/items/`
  - added the new `FONT_SIZE` enum value to the request property `variables/items/oneOf[#/components/schemas/VariableUpdate]/scopes/items/`
  - …12 more
- …earlier changes not shown

[Full history](https://skmtc.dev/figma/apis/figma-api/changes/v1/files/:file_key/variables/post.md)

---

[API](https://skmtc.dev/figma/apis/figma-api.md) · [All operations](https://skmtc.dev/figma/apis/figma-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/figma/figma-api/revisions/d7ab5681d84c/schema)