> ## 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.

# API Tool Variables

API operations for api tool variables. Browse the routes below for parameters, request examples, and responses.

API version: Selected per operation

## List variables

Returns every API tool variable in its API tool. An API tool variable is an input an API tool substitutes into its request. The call takes no paging parameters, so one request yields the whole set.

### Endpoint

```http
GET /v2/stable/api-tool-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`)."
}
```

#### `apiToolID`

Required · string

The ID of the API tool whose variables to list.

```json
{
  "type": "string",
  "description": "The ID of the API tool whose variables to list."
}
```

### Responses

#### 200

Returns every variable defined on a single API tool, selected by the apiToolID query parameter rather than across the whole project. Each carries the name the tool's request references and a description telling the agent what value to provide.

Schema:

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

Example:

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

### Request examples

#### cURL

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

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/api-tool-variable?projectID=<projectID>&environmentAlias=<environmentAlias>&apiToolID=<apiToolID>', {
  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/api-tool-variable?projectID=<projectID>&environmentAlias=<environmentAlias>&apiToolID=<apiToolID>',
    headers={'Authorization': 'Bearer <token>'},
)
data = response.json()
```

#### Voiceflow CLI

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


## Create variable

Adds an API tool variable to its API tool, an input an API tool substitutes into its request. The response carries the ID that later calls address it by.

### Endpoint

```http
POST /v2/stable/api-tool-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/StableAPIToolVariableCreateRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Creates the API tool variable and returns it, including its new ID and the apiToolID of the API tool it now belongs to.

Schema:

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

Example:

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

### Request examples

#### cURL

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

#### JavaScript

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

#### Python

```python
import requests

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

#### Voiceflow CLI

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


## Create many variables

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

### Endpoint

```http
POST /v2/stable/api-tool-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/StableAPIToolVariableCreateManyRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Returns the newly created API tool variables, each with its own ID and the apiToolID of the API tool it was attached to.

Schema:

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

Example:

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

### Request examples

#### cURL

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

#### JavaScript

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

#### Python

```python
import requests

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

#### Voiceflow CLI

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


## Delete variable

Deletes a single API tool variable by ID. An API tool variable is an input an API tool substitutes into its request. The response carries only a confirmation message, so refetch the API tool variables to see what is left.

### Endpoint

```http
DELETE /v1/stable/api-tool-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 API tool variable was deleted. Nothing but a message is returned, so refetch the tool's variables to see which names its request can still reference.

Schema:

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

Example:

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

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

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


## Get variable

Returns a single API tool variable by ID, with the fields that define it. An API tool variable is an input an API tool substitutes into its request.

### Endpoint

```http
GET /v2/stable/api-tool-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 API tool variable, with the name its tool's request references, the description that tells the agent what value to supply, and the ID of the API tool that owns it.

Schema:

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

Example:

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

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

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


## Update variable

Changes an existing API tool variable in place. The response carries only a confirmation message, so refetch the API tool variable to read its new values.

### Endpoint

```http
PATCH /v2/stable/api-tool-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/StableAPIToolVariableUpdateRequestV2"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the API tool variable was updated. The body is a confirmation rather than the updated variable, so fetch the variable again to see its current name and 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/api-tool-variable/<variableID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "<string>",
  "description": "<string>"
}'
```

#### JavaScript

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

#### Python

```python
import requests

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

#### Voiceflow CLI

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


## Schema definitions

### StableAPIToolVariableCreateManyRequestV2

```json
{
  "type": "object",
  "properties": {
    "apiToolID": {
      "type": "string",
      "description": "The ID of the API tool to create the variables under."
    },
    "variables": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^\\w{1,64}$",
            "description": "The name of the variable, referenced within the API tool request as {name}. Letters, digits and underscores only, at most 64 characters."
          },
          "description": {
            "nullable": true,
            "description": "A description of the variable, used by the agent to determine what value to provide.",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "apiToolID",
    "variables"
  ]
}
```

### StableAPIToolVariableCreateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^\\w{1,64}$",
      "description": "The name of the variable, referenced within the API tool request as {name}. Letters, digits and underscores only, at most 64 characters."
    },
    "apiToolID": {
      "type": "string",
      "description": "The ID of the API tool this variable belongs to."
    },
    "description": {
      "nullable": true,
      "description": "A description of the variable, used by the agent to determine what value to provide.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "apiToolID"
  ],
  "additionalProperties": false
}
```

### StableAPIToolVariableListResponseV2

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

### StableAPIToolVariableResponseV2

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

### StableAPIToolVariableUpdateRequestV2

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "pattern": "^\\w{1,64}$",
      "description": "The name of the variable, referenced within the API tool request as {name}. Letters, digits and underscores only, at most 64 characters."
    },
    "description": {
      "nullable": true,
      "description": "A description of the variable, used by the agent to determine what value to provide.",
      "type": "string"
    }
  },
  "additionalProperties": false
}
```

### StableAPIToolVariableV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "description": "The name of the variable, referenced within the API tool request as {name}. A name outside letters, digits and underscores can never be referenced."
    },
    "apiToolID": {
      "type": "string",
      "description": "The ID of the API tool this variable belongs to."
    },
    "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 description of the variable, used by the agent to determine what value to provide.",
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "apiToolID",
    "createdAt",
    "updatedAt",
    "description"
  ]
}
```

### 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"
  ]
}
```
