Current - 2026/09
Endpoint
GET
/v2/stable/api-tool

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Response

200 - application/json

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.

apiTools
object[]
required
StableAPIToolV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

url
object
name
string
required
body
object
settings
object
httpMethod
object
required
Available options: get, put, post, patch, delete
APIToolHTTPMethodType — see its attributes above
description
string

A description of what the API tool does, used by the agent to decide when to call it.

headers
object[]
StableAPIHeaderV2 — see its attributes above
queryParameters
object[]
StableAPIQueryParameterV2 — see its attributes above

Response

201 - application/json

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.

apiTool
object
required
StableAPIToolV2 — see its attributes above
unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/api-tool/batch

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

apiTools
object[]
required
StableAPIToolCreateRequestV2 — see its attributes above

Response

201 - application/json

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

apiTools
object[]
required
StableAPIToolV2 — see its attributes above
unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
DELETE
/v1/stable/api-tool/{toolID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the tool to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Response

200 - application/json

Confirms the API tool was deleted. Only a confirmation message comes back, so refetch the project's API tools to see what remains.

message
string
required

A human-readable message confirming the deletion.

Current - 2026/09
Endpoint
GET
/v2/stable/api-tool/{toolID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the tool to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Response

200 - application/json

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.

apiTool
object
required
StableAPIToolV2 — see its attributes above
Current - 2026/09
Endpoint
PATCH
/v2/stable/api-tool/{toolID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the tool to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

url
object
name
string
body
object
headers
object[]
StableAPIHeaderV2 — see its attributes above
settings
object
httpMethod
object
description
string

A description of what the API tool does, used by the agent to decide when to call it.

queryParameters
object[]
StableAPIQueryParameterV2 — see its attributes above

Response

200 - application/json

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.

message
string
required

A human-readable message confirming the update.

unresolvedReferences
object[]

References this write kept as literal text instead of binding, each with the reason. The write still succeeded.

StableUnresolvedReference — see its attributes above
Endpoint
GET
/v1/stable/api-tool/{toolID}/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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the API tool whose inputs to list.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Response

200 - application/json

Returns the API tool's inputs, sorted by name, each one a required string.

inputs
object[]
required

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.

StableExecuteInput — see its attributes above
Use this operation to test agent behavior or execute tools with controlled inputs. For production conversation integrations, use the Agent runtime. Tool execution can affect connected services.
Endpoint
POST
/v1/stable/api-tool/{toolID}/execute

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

toolID
string
required

The ID of the API tool to execute.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

inputs
object

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.

Response

200 - application/json

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.

success
boolean
required

Whether the tool ran and reported no error.

latencyMs
number
required

How long the run took, in milliseconds, measured by this API around the call.

error
string
required

Why the run failed when success is false, otherwise null. Secret values read [secret].

truncated
boolean
required

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
object
required

What the endpoint returned. Null only when general-runtime did not answer in time.

Schemas

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.