> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Variables

A variable is a named slot of project state an agent can read and write. Use this API to list, retrieve, create, update, and delete variables in a project environment.

API version: Selected per operation

## List variables

Returns every variable in the project. A variable is a named slot of project state an agent can read and write. The call takes no paging parameters, so one request yields the whole set.

### Endpoint

```http
GET /v2/stable/variable
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns every variable defined in the project environment, each with its name, description, default value, color, and whether the platform owns it as a system variable.

Schema:

```json
{
  "$ref": "#/components/schemas/StableVariableListResponseV2"
}
```

Example:

```json
{
  "variables": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "<string>",
      "isSystem": true,
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "description": "<string>",
      "defaultValue": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable list --project-id <projectID> --environment-alias <environmentAlias>
```


## Create variable

Adds a variable to the project, a named slot of project state an agent can read and write. The name takes letters, digits and underscores only, up to 64 characters, and must not already be used by a variable or entity in the environment. The response carries the ID that later calls address it by.

### Endpoint

```http
POST /v2/stable/variable
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableVariableCreateRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Returns the newly created variable in full, including the ID assigned to it and its creation timestamps.

Schema:

```json
{
  "$ref": "#/components/schemas/StableVariableResponseV2"
}
```

Example:

```json
{
  "variable": {
    "id": "<string>",
    "name": "<string>",
    "color": "<string>",
    "isSystem": true,
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "description": "<string>",
    "defaultValue": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "color": "<string>",
  "description": "<string>",
  "defaultValue": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "color": "<string>",
    "description": "<string>",
    "defaultValue": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/variable?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "color": "<string>",
      "description": "<string>",
      "defaultValue": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "color": "<string>",
  "description": "<string>",
  "defaultValue": "<string>"
}
JSON
```


## Create many variables

Adds several variables to the project in one request, each taking the fields the single-create call takes, including its name rules. The response carries the created variables in the same shape the list call returns.

### Endpoint

```http
POST /v2/stable/variable/batch
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/StableVariableCreateManyRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Returns the variables the request created, as an array, each carrying the ID assigned to it.

Schema:

```json
{
  "$ref": "#/components/schemas/StableVariableListResponseV2"
}
```

Example:

```json
{
  "variables": [
    {
      "id": "<string>",
      "name": "<string>",
      "color": "<string>",
      "isSystem": true,
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "description": "<string>",
      "defaultValue": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/variable/batch?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "variables": [
    {
      "name": "<string>",
      "color": "<string>",
      "description": "<string>",
      "defaultValue": "<string>"
    }
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/variable/batch?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "variables": [
      {
        "name": "<string>",
        "color": "<string>",
        "description": "<string>",
        "defaultValue": "<string>"
      }
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/variable/batch?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "variables": [
        {
          "name": "<string>",
          "color": "<string>",
          "description": "<string>",
          "defaultValue": "<string>"
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable create-many --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "variables": [
    {
      "name": "<string>",
      "color": "<string>",
      "description": "<string>",
      "defaultValue": "<string>"
    }
  ]
}
JSON
```


## Delete variable

Deletes a single variable by ID. A variable is a named slot of project state an agent can read and write. The response carries only a confirmation message, so refetch the variables to see what is left.

### Endpoint

```http
DELETE /v1/stable/variable/{variableID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `variableID`

Required · string

The ID of the variable to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Confirms the variable was deleted. Only a message comes back, so refresh any cached copy of the project's variables.

Schema:

```json
{
  "$ref": "#/components/schemas/StableDeleteResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

#### 404

No variable with that ID exists in the project and environment. A delete that has already succeeded returns this on a second attempt, so the operation is not idempotent - treat a 404 here as "already gone" rather than as a failure worth retrying.

### Request examples

#### cURL

```bash
curl --request DELETE \
  --url 'https://realtime-api.voiceflow.com/v1/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v1/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.delete(
    'https://realtime-api.voiceflow.com/v1/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable delete --variable-id <variableID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Get variable

Returns a single variable by ID, with the fields that define it. A variable is a named slot of project state an agent can read and write.

### Endpoint

```http
GET /v2/stable/variable/{variableID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `variableID`

Required · string

The ID of the variable to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Responses

#### 200

Returns a single variable by ID, carrying its current description, default value, color, and timestamps.

Schema:

```json
{
  "$ref": "#/components/schemas/StableVariableResponseV2"
}
```

Example:

```json
{
  "variable": {
    "id": "<string>",
    "name": "<string>",
    "color": "<string>",
    "isSystem": true,
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "description": "<string>",
    "defaultValue": "<string>"
  }
}
```

### Request examples

#### cURL

```bash
curl --request GET \
  --url 'https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer <token>',
  },
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.get(
    'https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable get --variable-id <variableID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Update variable

Changes an existing variable in place. Send `name` only when renaming, because a new name must use letters, digits and underscores and be unused by any variable or entity in the environment. The response carries only a confirmation message, so refetch the variable to read its new values.

### Endpoint

```http
PATCH /v2/stable/variable/{variableID}
```

Server: https://realtime-api.voiceflow.com

### Authentication

```json
[
  {
    "token": []
  }
]
```

`token`:

```json
{
  "scheme": "bearer",
  "bearerFormat": "JWT",
  "type": "http",
  "description": "Voiceflow bearer token"
}
```

### Path parameters

#### `variableID`

Required · string

The ID of the variable to operate on.

```json
{
  "type": "string"
}
```

### Query parameters

#### `projectID`

Required · string

The ID of the project to operate on.

```json
{
  "type": "string",
  "description": "The ID of the project to operate on."
}
```

#### `environmentAlias`

Required · string

The alias of the environment to operate on (e.g. `main`).

```json
{
  "type": "string",
  "description": "The alias of the environment to operate on (e.g. `main`)."
}
```

### Request body

Required

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "allOf": [
          {
            "$ref": "#/components/schemas/StableVariableUpdateRequestV2"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the variable was updated. The body is a message rather than the revised variable, so read the variable back to see its new default value or description.

Schema:

```json
{
  "$ref": "#/components/schemas/StableUpdateResponse"
}
```

Example:

```json
{
  "message": "<string>"
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "color": "<string>",
  "description": "<string>",
  "defaultValue": "<string>"
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "name": "<string>",
    "color": "<string>",
    "description": "<string>",
    "defaultValue": "<string>"
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v2/stable/variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "name": "<string>",
      "color": "<string>",
      "description": "<string>",
      "defaultValue": "<string>"
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf variable update --variable-id <variableID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "name": "<string>",
  "color": "<string>",
  "description": "<string>",
  "defaultValue": "<string>"
}
JSON
```


## Schema definitions

### StableDeleteResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the deletion."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    }
  },
  "required": [
    "message"
  ]
}
```

### StableVariableCreateManyRequestV2

```json
{
  "type": "object",
  "properties": {
    "variables": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableVariableCreateRequestV2"
      }
    }
  },
  "required": [
    "variables"
  ]
}
```

### StableVariableCreateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^\\w{1,64}$",
      "description": "The name of the variable. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a text field binds to. Must not already be used by a variable or an entity in this environment. When updating, omit this field unless you are renaming: a variable stored before this rule can hold a name outside the grammar, and echoing that name back would be rejected."
    },
    "color": {
      "type": "string",
      "description": "The display color of the variable in the Voiceflow editor, as a hex code from the editor's color picker. Use #515A63 (the editor's default) unless the user asks for a color; otherwise pick the closest of #5B9FD7, #CB627B, #56B365, #DC8879, #9A63BC. Do not invent other hex codes."
    },
    "description": {
      "nullable": true,
      "description": "A short description of what the variable stores.",
      "type": "string"
    },
    "defaultValue": {
      "nullable": true,
      "description": "The initial value of the variable at the start of a conversation.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "color"
  ],
  "additionalProperties": false
}
```

### StableVariableListResponseV2

```json
{
  "type": "object",
  "properties": {
    "variables": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableVariableV2"
      }
    }
  },
  "required": [
    "variables"
  ]
}
```

### StableVariableResponseV2

```json
{
  "type": "object",
  "properties": {
    "variable": {
      "$ref": "#/components/schemas/StableVariableV2"
    }
  },
  "required": [
    "variable"
  ]
}
```

### StableVariableUpdateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^\\w{1,64}$",
      "description": "The name of the variable. Letters, digits and underscores only, at most 64 characters — this is what a {token} in a text field binds to. Must not already be used by a variable or an entity in this environment. When updating, omit this field unless you are renaming: a variable stored before this rule can hold a name outside the grammar, and echoing that name back would be rejected."
    },
    "color": {
      "type": "string",
      "description": "The display color of the variable in the Voiceflow editor, as a hex code from the editor's color picker. Use #515A63 (the editor's default) unless the user asks for a color; otherwise pick the closest of #5B9FD7, #CB627B, #56B365, #DC8879, #9A63BC. Do not invent other hex codes."
    },
    "description": {
      "nullable": true,
      "description": "A short description of what the variable stores.",
      "type": "string"
    },
    "defaultValue": {
      "nullable": true,
      "description": "The initial value of the variable at the start of a conversation.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### StableVariableV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "The name of the variable. This is what a {token} in a text field binds to, so a name outside letters, digits and underscores can never be referenced."
    },
    "color": {
      "type": "string",
      "description": "The display color of the variable in the Voiceflow editor."
    },
    "isSystem": {
      "type": "boolean",
      "description": "Whether this is a built-in system variable, which cannot be updated or deleted."
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "description": {
      "nullable": true,
      "description": "A short description of what the variable stores.",
      "type": "string"
    },
    "defaultValue": {
      "nullable": true,
      "description": "The initial value of the variable at the start of a conversation.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "color",
    "isSystem",
    "createdAt",
    "updatedAt",
    "description",
    "defaultValue"
  ]
}
```
