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

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

API version: Selected per operation

## List API tools

Returns every API tool in the environment. An API tool is a saved HTTP request an agent can make; its URL, header values, and query parameter values are plain strings that reference the tool's inputs as {input_name}. The call takes no paging parameters, so one request yields the whole set.

### Endpoint

```http
GET /v2/stable/api-tool
```

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 API tool saved in the project's environment, each with its HTTP method, URL, headers, query parameters, body, and the description the agent uses to decide when to call it.

Schema:

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

Example:

```json
{
  "apiTools": [
    {
      "id": "<string>",
      "name": "<string>",
      "url": "<ToolInputReferenceString>",
      "body": "<StableAPIToolBody>",
      "image": "<string>",
      "headers": [
        "<StableAPIHeaderV2>"
      ],
      "settings": "<APIToolSettings>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "httpMethod": "get",
      "description": "<string>",
      "queryParameters": [
        "<StableAPIQueryParameterV2>"
      ]
    }
  ]
}
```

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

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


## Create API tool

Adds an API tool to the environment, a saved HTTP request an agent can make. The URL, header values, and query parameter values are plain strings that reference the tool's inputs as {input_name}, and the response carries the ID that later calls address it by.

### Endpoint

```http
POST /v2/stable/api-tool
```

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/StableAPIToolCreateRequestV2"
      }
    }
  }
}
```

### Responses

#### 201

Creates the API tool and returns it in full, including its new ID and the request it will send: HTTP method, URL, headers, query parameters, and body.

Schema:

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

Example:

```json
{
  "apiTool": {
    "id": "<string>",
    "name": "<string>",
    "url": "<string>",
    "body": "<StableAPIToolRawBody>",
    "image": "<string>",
    "headers": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ],
    "settings": {
      "timeoutMs": 0
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "httpMethod": "get",
    "description": "<string>",
    "queryParameters": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ]
  },
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<string>",
  "name": "<string>",
  "body": {
    "type": "raw-input",
    "contentType": "<APIToolContentType>",
    "content": "<ToolInputReferenceString>"
  },
  "settings": {
    "timeoutMs": 0
  },
  "httpMethod": "get",
  "description": "<string>",
  "headers": [],
  "queryParameters": []
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "<string>",
    "name": "<string>",
    "body": {
      "type": "raw-input",
      "contentType": "<APIToolContentType>",
      "content": "<ToolInputReferenceString>"
    },
    "settings": {
      "timeoutMs": 0
    },
    "httpMethod": "get",
    "description": "<string>",
    "headers": [],
    "queryParameters": []
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/api-tool?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "url": "<string>",
      "name": "<string>",
      "body": {
        "type": "raw-input",
        "contentType": "<APIToolContentType>",
        "content": "<ToolInputReferenceString>"
      },
      "settings": {
        "timeoutMs": 0
      },
      "httpMethod": "get",
      "description": "<string>",
      "headers": [],
      "queryParameters": []
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf api-tool create --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "url": "<string>",
  "name": "<string>",
  "body": {
    "type": "raw-input",
    "contentType": "<APIToolContentType>",
    "content": "<ToolInputReferenceString>"
  },
  "settings": {
    "timeoutMs": 0
  },
  "httpMethod": "get",
  "description": "<string>",
  "headers": [],
  "queryParameters": []
}
JSON
```


## Create many API tools

Adds several API tools to the environment in one request, each taking the fields the single-create call takes, with URL and header values as plain strings. The response carries the created API tools in the same shape the list call returns.

### Endpoint

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

### Responses

#### 201

Creates every API tool in the request and returns them all, each with its own ID and complete saved request definition.

Schema:

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

Example:

```json
{
  "apiTools": [
    {
      "id": "<string>",
      "name": "<string>",
      "url": "<ToolInputReferenceString>",
      "body": "<StableAPIToolBody>",
      "image": "<string>",
      "headers": [
        "<StableAPIHeaderV2>"
      ],
      "settings": "<APIToolSettings>",
      "createdAt": "2026-09-10T00:00:00.000Z",
      "updatedAt": "2026-09-10T00:00:00.000Z",
      "httpMethod": "get",
      "description": "<string>",
      "queryParameters": [
        "<StableAPIQueryParameterV2>"
      ]
    }
  ],
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v2/stable/api-tool/batch?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "apiTools": [
    {
      "url": "<ToolInputReferenceString>",
      "name": "<string>",
      "body": "<StableAPIToolBody>",
      "settings": "<APIToolSettings>",
      "httpMethod": "get",
      "description": "<string>",
      "headers": [],
      "queryParameters": []
    }
  ]
}'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v2/stable/api-tool/batch?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "apiTools": [
        {
          "url": "<ToolInputReferenceString>",
          "name": "<string>",
          "body": "<StableAPIToolBody>",
          "settings": "<APIToolSettings>",
          "httpMethod": "get",
          "description": "<string>",
          "headers": [],
          "queryParameters": []
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf api-tool create-many --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "apiTools": [
    {
      "url": "<ToolInputReferenceString>",
      "name": "<string>",
      "body": "<StableAPIToolBody>",
      "settings": "<APIToolSettings>",
      "httpMethod": "get",
      "description": "<string>",
      "headers": [],
      "queryParameters": []
    }
  ]
}
JSON
```


## Delete API tool

Deletes a single API tool by ID. An API tool is a saved HTTP request an agent can make. The response carries only a confirmation message, so refetch the API tools to see what is left.

### Endpoint

```http
DELETE /v1/stable/api-tool/{toolID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `toolID`

Required · string

The ID of the tool 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 was deleted. Only a confirmation message comes back, so refetch the project's API tools to see what remains.

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/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>'
```

#### JavaScript

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

#### Voiceflow CLI

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


## Get API tool

Returns a single API tool by ID, with the fields that define it. An API tool is a saved HTTP request an agent can make; its URL, header values, and query parameter values come back as plain strings.

### Endpoint

```http
GET /v2/stable/api-tool/{toolID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `toolID`

Required · string

The ID of the tool 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, with the complete request it sends: HTTP method, URL, headers, query parameters, and body, plus any settings saved on it.

Schema:

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

Example:

```json
{
  "apiTool": {
    "id": "<string>",
    "name": "<string>",
    "url": "<string>",
    "body": "<StableAPIToolRawBody>",
    "image": "<string>",
    "headers": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ],
    "settings": {
      "timeoutMs": 0
    },
    "createdAt": "2026-09-10T00:00:00.000Z",
    "updatedAt": "2026-09-10T00:00:00.000Z",
    "httpMethod": "get",
    "description": "<string>",
    "queryParameters": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ]
  }
}
```

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

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


## Update API tool

Changes an existing API tool in place, taking URL and header values as plain strings that reference the tool's inputs as {input_name}. The response lists any references that did not resolve; read the API tool again to see its new values.

### Endpoint

```http
PATCH /v2/stable/api-tool/{toolID}
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `toolID`

Required · string

The ID of the tool 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/StableAPIToolUpdateRequestV2"
          }
        ]
      }
    }
  }
}
```

### Responses

#### 200

Confirms the API tool was updated. The response carries a message only, not the revised tool, so fetch the API tool again to read back the request it now sends.

Schema:

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

Example:

```json
{
  "message": "<string>",
  "unresolvedReferences": [
    {
      "path": "<string>",
      "token": "<string>",
      "reason": "unknown"
    }
  ]
}
```

### Request examples

#### cURL

```bash
curl --request PATCH \
  --url 'https://realtime-api.voiceflow.com/v2/stable/api-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "url": "<string>",
  "name": "<string>",
  "body": "<StableAPIToolRawBody>",
  "headers": [
    {
      "key": "<string>",
      "value": "<ToolInputReferenceString>"
    }
  ],
  "settings": {
    "timeoutMs": 0
  },
  "httpMethod": "get",
  "description": "<string>",
  "queryParameters": [
    {
      "key": "<string>",
      "value": "<ToolInputReferenceString>"
    }
  ]
}'
```

#### JavaScript

```javascript
const response = await fetch('https://realtime-api.voiceflow.com/v2/stable/api-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>', {
  method: 'PATCH',
  headers: {
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "url": "<string>",
    "name": "<string>",
    "body": "<StableAPIToolRawBody>",
    "headers": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ],
    "settings": {
      "timeoutMs": 0
    },
    "httpMethod": "get",
    "description": "<string>",
    "queryParameters": [
      {
        "key": "<string>",
        "value": "<ToolInputReferenceString>"
      }
    ]
  }),
});
const data = await response.json();
```

#### Python

```python
import requests

response = requests.patch(
    'https://realtime-api.voiceflow.com/v2/stable/api-tool/<toolID>?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "url": "<string>",
      "name": "<string>",
      "body": "<StableAPIToolRawBody>",
      "headers": [
        {
          "key": "<string>",
          "value": "<ToolInputReferenceString>"
        }
      ],
      "settings": {
        "timeoutMs": 0
      },
      "httpMethod": "get",
      "description": "<string>",
      "queryParameters": [
        {
          "key": "<string>",
          "value": "<ToolInputReferenceString>"
        }
      ]
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf api-tool update --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "url": "<string>",
  "name": "<string>",
  "body": "<StableAPIToolRawBody>",
  "headers": [
    {
      "key": "<string>",
      "value": "<ToolInputReferenceString>"
    }
  ],
  "settings": {
    "timeoutMs": 0
  },
  "httpMethod": "get",
  "description": "<string>",
  "queryParameters": [
    {
      "key": "<string>",
      "value": "<ToolInputReferenceString>"
    }
  ]
}
JSON
```


## Get API tool schema

Returns the input variables an API tool declares, which are the names the execute call needs a value for. Call it before executing so the request body has every input.

### Endpoint

```http
GET /v1/stable/api-tool/{toolID}/schema
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `toolID`

Required · string

The ID of the API tool whose inputs to list.

```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 the API tool's inputs, sorted by name, each one a required string.

Schema:

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

Example:

```json
{
  "inputs": [
    {
      "name": "<string>",
      "type": "<string>",
      "required": true,
      "description": "<string>"
    }
  ]
}
```

### Request examples

#### cURL

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

#### JavaScript

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

#### Voiceflow CLI

```bash
vf api-tool get-schema --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias>
```


## Execute API tool

Sends an API tool's saved request once, filling its input placeholders from the inputs in the body. The call stops at the tool's timeout or 18 seconds, whichever is shorter, and nothing is saved.

### Endpoint

```http
POST /v1/stable/api-tool/{toolID}/execute
```

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

### Authentication

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

`token`:

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

### Path parameters

#### `toolID`

Required · string

The ID of the API tool to execute.

```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": {
        "$ref": "#/components/schemas/StableAPIToolExecuteRequest"
      }
    }
  }
}
```

### Responses

#### 200

Returns the endpoint's HTTP status, status text, headers, and parsed body, with success, latencyMs, and error fields. Secret values read [secret] wherever they appear.

Schema:

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

Example:

```json
{
  "success": true,
  "latencyMs": 0,
  "error": "<string>",
  "truncated": true,
  "output": {
    "status": 0,
    "statusText": "<string>",
    "headers": {},
    "body": null
  }
}
```

### Request examples

#### cURL

```bash
curl --request POST \
  --url 'https://realtime-api.voiceflow.com/v1/stable/api-tool/<toolID>/execute?projectID=<projectID>&environmentAlias=<environmentAlias>' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "inputs": {}
}'
```

#### JavaScript

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

#### Python

```python
import requests

response = requests.post(
    'https://realtime-api.voiceflow.com/v1/stable/api-tool/<toolID>/execute?projectID=<projectID>&environmentAlias=<environmentAlias>',
    headers={'Authorization': 'Bearer <token>'},
    json={
      "inputs": {}
    },
)
data = response.json()
```

#### Voiceflow CLI

```bash
vf api-tool execute --tool-id <toolID> --project-id <projectID> --environment-alias <environmentAlias> <<'JSON'
{
  "inputs": {}
}
JSON
```


## Schema definitions

### APIToolContentType

```json
{
  "type": "string",
  "enum": [
    "text",
    "json",
    "xml"
  ],
  "x-enumNames": [
    "TEXT",
    "JSON",
    "XML"
  ]
}
```

### APIToolHTTPMethodType

```json
{
  "type": "string",
  "enum": [
    "get",
    "put",
    "post",
    "patch",
    "delete"
  ],
  "x-enumNames": [
    "GET",
    "PUT",
    "POST",
    "PATCH",
    "DELETE"
  ]
}
```

### APIToolSettings

```json
{
  "type": "object",
  "properties": {
    "timeoutMs": {
      "type": "integer",
      "minimum": 0,
      "exclusiveMinimum": true,
      "maximum": 600000
    }
  }
}
```

### ExecuteInputString

```json
{
  "type": "string",
  "description": "A value sent to a tool for one run, never stored. Plain text. {secret_name} inserts a project secret: the server fills in the value this environment would use in a conversation, and the value reads [secret] wherever it appears in the result. Brace text is a token when the text between the braces has no space at either end and holds only letters, digits, underscores, inner spaces, ., [, ], $ or -. A token that names no project secret, such as {customer_id} or {var name}, is refused before the tool runs, because a single run has no conversation to read a variable from: pass the value itself. Any other brace text is sent as written, so code, JSON and GraphQL such as query { user { id } } run as they are. Compact brace text such as {id} still reads as a token: write { id } to send it as text. A secret whose name is not letters, digits and underscores cannot be referenced. A {secret_name} token is filled in only in a top-level string value of inputs. Inside a nested object or array it is sent as written, and no secret is filled in."
}
```

### StableAPIHeaderV2

```json
{
  "type": "object",
  "properties": {
    "key": {
      "nullable": true,
      "description": "The name of the HTTP header to send with the request.",
      "type": "string"
    },
    "value": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    }
  },
  "required": [
    "key",
    "value"
  ],
  "additionalProperties": false
}
```

### StableAPIQueryParameterV2

```json
{
  "type": "object",
  "properties": {
    "key": {
      "nullable": true,
      "description": "The name of the query parameter to append to the request URL.",
      "type": "string"
    },
    "value": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    }
  },
  "required": [
    "key",
    "value"
  ],
  "additionalProperties": false
}
```

### StableAPIToolBody

```json
{
  "oneOf": [
    {
      "$ref": "#/components/schemas/StableAPIToolRawBody"
    },
    {
      "$ref": "#/components/schemas/StableAPIToolFormDataBody"
    },
    {
      "$ref": "#/components/schemas/StableAPIToolURLEncodedBody"
    }
  ]
}
```

### StableAPIToolCreateManyRequestV2

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

### StableAPIToolCreateRequestV2

```json
{
  "type": "object",
  "properties": {
    "url": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    },
    "name": {
      "type": "string"
    },
    "body": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableAPIToolBody"
        }
      ]
    },
    "settings": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/APIToolSettings"
        }
      ]
    },
    "httpMethod": {
      "$ref": "#/components/schemas/APIToolHTTPMethodType"
    },
    "description": {
      "nullable": true,
      "description": "A description of what the API tool does, used by the agent to decide when to call it.",
      "type": "string"
    },
    "headers": {
      "default": [],
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIHeaderV2"
      }
    },
    "queryParameters": {
      "default": [],
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIQueryParameterV2"
      }
    }
  },
  "required": [
    "name",
    "httpMethod"
  ],
  "additionalProperties": false
}
```

### StableAPIToolExecuteOutput

```json
{
  "type": "object",
  "properties": {
    "status": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "The HTTP status the endpoint returned. 408 when it did not answer within the tool's timeout or 18 seconds, whichever is shorter."
    },
    "statusText": {
      "type": "string",
      "description": "The HTTP status text the endpoint returned."
    },
    "headers": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "The response headers. Secret values read `[secret]`."
    },
    "body": {
      "description": "The response body, parsed as JSON when the endpoint returned JSON. Secret values read `[secret]`."
    }
  },
  "required": [
    "status",
    "statusText",
    "headers",
    "body"
  ]
}
```

### StableAPIToolExecuteRequest

```json
{
  "type": "object",
  "properties": {
    "inputs": {
      "default": {},
      "description": "A value for each of the API tool's input variables, keyed by input name. Each value replaces the tool's {input_name} placeholder in the URL, headers, query and body. Every declared input needs a value, and a name the tool does not declare is refused. List them with get_schema.",
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/ExecuteInputString"
      }
    }
  },
  "additionalProperties": false
}
```

### StableAPIToolExecuteResponse

```json
{
  "type": "object",
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Whether the tool ran and reported no error."
    },
    "latencyMs": {
      "type": "number",
      "description": "How long the run took, in milliseconds, measured by this API around the call."
    },
    "error": {
      "nullable": true,
      "description": "Why the run failed when `success` is false, otherwise null. Secret values read `[secret]`.",
      "type": "string"
    },
    "truncated": {
      "type": "boolean",
      "description": "Whether a returned payload was over 64 KB and was cut to its first 64 KB of JSON text, which then arrives as a string."
    },
    "output": {
      "nullable": true,
      "description": "What the endpoint returned. Null only when general-runtime did not answer in time.",
      "allOf": [
        {
          "$ref": "#/components/schemas/StableAPIToolExecuteOutput"
        }
      ]
    }
  },
  "required": [
    "success",
    "latencyMs",
    "error",
    "truncated",
    "output"
  ]
}
```

### StableAPIToolFormDataBody

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "form-data"
      ],
      "x-enumNames": [
        "FORM_DATA"
      ]
    },
    "formData": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIToolKeyValue"
      }
    }
  },
  "required": [
    "type",
    "formData"
  ]
}
```

### StableAPIToolKeyValue

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "key": {
      "nullable": true,
      "type": "string"
    },
    "value": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    }
  },
  "required": [
    "id",
    "key",
    "value"
  ]
}
```

### StableAPIToolListResponseV2

```json
{
  "type": "object",
  "properties": {
    "apiTools": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIToolV2"
      }
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    }
  },
  "required": [
    "apiTools"
  ]
}
```

### StableAPIToolRawBody

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "raw-input"
      ],
      "x-enumNames": [
        "RAW_INPUT"
      ]
    },
    "contentType": {
      "allOf": [
        {
          "$ref": "#/components/schemas/APIToolContentType"
        }
      ]
    },
    "content": {
      "$ref": "#/components/schemas/ToolInputReferenceString"
    }
  },
  "required": [
    "type",
    "content"
  ]
}
```

### StableAPIToolReadListResponse

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

### StableAPIToolReadResponse

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

### StableAPIToolResponseV2

```json
{
  "type": "object",
  "properties": {
    "apiTool": {
      "$ref": "#/components/schemas/StableAPIToolV2"
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    }
  },
  "required": [
    "apiTool"
  ]
}
```

### StableAPIToolSchemaReadResponse

```json
{
  "type": "object",
  "properties": {
    "inputs": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableExecuteInput"
      },
      "description": "The inputs execute takes, one per input variable, sorted by name. Every one is a required string. A credential input usually gets its secret from the attachment's default; write that secret's name as {secret_name} in the value."
    }
  },
  "required": [
    "inputs"
  ]
}
```

### StableAPIToolURLEncodedBody

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "url-encoded"
      ],
      "x-enumNames": [
        "URL_ENCODED"
      ]
    },
    "params": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIToolKeyValue"
      }
    }
  },
  "required": [
    "type",
    "params"
  ]
}
```

### StableAPIToolUpdateRequestV2

```json
{
  "type": "object",
  "properties": {
    "url": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    },
    "name": {
      "type": "string"
    },
    "body": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableAPIToolBody"
        }
      ]
    },
    "headers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIHeaderV2"
      }
    },
    "settings": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/APIToolSettings"
        }
      ]
    },
    "httpMethod": {
      "allOf": [
        {
          "$ref": "#/components/schemas/APIToolHTTPMethodType"
        }
      ]
    },
    "description": {
      "nullable": true,
      "description": "A description of what the API tool does, used by the agent to decide when to call it.",
      "type": "string"
    },
    "queryParameters": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIQueryParameterV2"
      }
    }
  },
  "additionalProperties": false
}
```

### StableAPIToolV2

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "url": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/ToolInputReferenceString"
        }
      ]
    },
    "body": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/StableAPIToolBody"
        }
      ]
    },
    "image": {
      "nullable": true,
      "description": "The URL of the image displayed for the API tool in the UI.",
      "type": "string"
    },
    "headers": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIHeaderV2"
      }
    },
    "settings": {
      "nullable": true,
      "allOf": [
        {
          "$ref": "#/components/schemas/APIToolSettings"
        }
      ]
    },
    "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))$"
    },
    "httpMethod": {
      "$ref": "#/components/schemas/APIToolHTTPMethodType"
    },
    "description": {
      "nullable": true,
      "description": "A description of what the API tool does, used by the agent to decide when to call it.",
      "type": "string"
    },
    "queryParameters": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableAPIQueryParameterV2"
      }
    }
  },
  "required": [
    "id",
    "name",
    "url",
    "body",
    "image",
    "headers",
    "createdAt",
    "updatedAt",
    "httpMethod",
    "description",
    "queryParameters"
  ]
}
```

### StableDeleteResponse

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

### StableExecuteInput

```json
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The input name, used as its key in `inputs` when executing."
    },
    "type": {
      "type": "string",
      "description": "The JSON type the value must have, such as `string`, `number` or `boolean`. Always `string` for a function or an API tool, and `any` when an MCP tool does not say."
    },
    "required": {
      "type": "boolean",
      "description": "Whether execute needs a value for this input."
    },
    "description": {
      "nullable": true,
      "description": "What the input holds, as the tool describes it.",
      "type": "string"
    }
  },
  "required": [
    "name",
    "type",
    "required",
    "description"
  ]
}
```

### StableTextUpdateResponse

```json
{
  "type": "object",
  "properties": {
    "message": {
      "type": "string",
      "description": "A human-readable message confirming the update."
    },
    "unresolvedReferences": {
      "description": "References this write kept as literal text instead of binding, each with the reason. The write still succeeded.",
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/StableUnresolvedReference"
      }
    }
  },
  "required": [
    "message"
  ]
}
```

### StableUnresolvedReference

```json
{
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "description": "Dotted path of the field that carried it, e.g. `knowledgeBaseTool.filters[0].defaultValue`."
    },
    "token": {
      "type": "string",
      "description": "The reference as written, without braces."
    },
    "reason": {
      "type": "string",
      "enum": [
        "unknown",
        "secret-not-allowed",
        "path-on-non-variable",
        "resource-id",
        "invalid-name",
        "dangling"
      ],
      "description": "`unknown`: no variable or entity of that name. `secret-not-allowed`: the name is a project secret and this field does not accept one. `path-on-non-variable`: only a variable has fields. `resource-id`: a bare resource id, not a name. `invalid-name`: outside the `^\\w{1,64}$` name grammar. `dangling`: the reference rendered as a bare id, because its row is gone or its name is outside the name grammar.",
      "x-enumNames": [
        "UNKNOWN",
        "SECRET_NOT_ALLOWED",
        "PATH_ON_NON_VARIABLE",
        "RESOURCE_ID",
        "INVALID_NAME",
        "DANGLING"
      ]
    }
  },
  "required": [
    "path",
    "token",
    "reason"
  ]
}
```

### ToolInputReferenceString

```json
{
  "type": "string",
  "description": "Plain text. {input_name} inserts one of THIS API tool's declared input variables — not a project variable and not a secret. {input_name.path} reads a field of that input; the declared input is the base name, so {order.id} declares an input named order. Escape a literal { or \\ with a backslash. A name matching no declared input declares one on this tool as part of the write. A bare 24-hex token is the residue of a deleted reference rather than a name: it declares nothing and is reported as resource-id. Until an attachment binds a default for it, a declared input is filled by the model at runtime. A credential reaches an API tool through the attachment's inputVariables[<name>].defaultValue."
}
```
