Current - 2026/09
Endpoint
GET
/v2/stable/agent

Returns the environment's agent: the global prompt, the instructions that route a turn, and the settings wrapping both. The prompt and instructions are plain Markdown strings, and each entry in the agent's playbook and workflow lists can carry a condition.

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

includeInstructions
boolean
default:false

Instructions can be tens of thousands of lines. Leave this off and use read_instructions to page through them only when you need the text.

includePrompt
boolean
default:false

The global prompt can be tens of thousands of lines. Leave this off and use read_prompt to page through it only when you need the text.

Response

200 - application/json

Returns the agent's whole configuration: its model settings, prompt, instructions, the playbooks and workflows attached to it, and its system tool setup. The voice section is optional and may be absent.

agent
object
required
StableAgentReadV2 — see its attributes above
Current - 2026/09
Endpoint
PATCH
/v2/stable/agent

Changes the agent that shapes every turn - its global prompt, its routing instructions, or its settings - in the environment named by the request. The prompt and instructions are sent as plain Markdown strings.

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

prompt
object
endTool
object
cardTool
object
playbooks
object[]

Playbooks available for the agent to invoke. This list REPLACES the registry: send the complete list you want, or omit the field to leave routing untouched. An agent with no playbooks AND no workflows registered cannot run - the runtime fails the conversation - so never send an empty list unless workflows still holds at least one.

workflows
object[]

Workflows available for the agent to invoke. This list REPLACES the registry: send the complete list you want, or omit the field to leave routing untouched. An agent with no workflows AND no playbooks registered cannot run, so never send an empty list unless playbooks still holds at least one.

buttonTool
object
instructions
object
skipTurnTool
object
pathToolOrder
string[]

The ordered list of path tool IDs that controls the order of the agent exit paths.

webSearchTool
object
callForwardTool
object
knowledgeBaseTool
object
includeGuidelines
boolean

Whether to append the default prompting guidelines to the global prompt.

llm
object
voice
object

Response

200 - application/json

Confirms the agent's configuration was updated, and lists any references or mentions in the new text that did not resolve. The body is a message rather than the new configuration, so read the agent back to see what it holds now.

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
unresolvedMentions
object[]

Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.

StableUnresolvedMention — see its attributes above
Current - 2026/09
Endpoint
GET
/v2/stable/agent/instructions

Returns one page of the main agent's routing instructions, each line prefixed with its 1-based number, so a later patch can quote text exactly as it appears. offset and limit pick the page; the totals in the response cover the whole document.

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

offset
integer
default:1

The 1-based line number to start from. Clamped to the last line of the document.

Minimum: 1 · Maximum: 9007199254740991
limit
integer
default:400

The maximum number of lines to return. A page is also capped at 24,000 characters, so a page of very long lines can come back shorter than this — follow nextOffset while hasMore is true.

Minimum: 1 · Maximum: 2000

Response

200 - application/json

Returns the requested lines of the main agent's instructions as one numbered block, with the page's actual offset, its line count, the document's total lines and characters, and whether more lines follow.

content
string
required

The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.

offset
integer
required

The line number this page actually starts at, after clamping.

Minimum: -9007199254740991 · Maximum: 9007199254740991
returnedLines
integer
required

How many lines this page carries.

Minimum: -9007199254740991 · Maximum: 9007199254740991
totalLines
integer
required

How many lines the whole document has.

Minimum: -9007199254740991 · Maximum: 9007199254740991
totalCharacters
integer
required

How many characters the whole document has.

Minimum: -9007199254740991 · Maximum: 9007199254740991
hasMore
boolean
required

Whether lines remain after this page.

nextOffset
integer
required

The first line not returned, or null when there is nothing more to read.

Minimum: -9007199254740991 · Maximum: 9007199254740991
note
string

Names the backticked names on this page that are links to a tool, playbook or workflow. A link reads as the resource's current name, whatever spelling the write used. Absent when the page shows no link.

Current - 2026/09
Endpoint
PATCH
/v2/stable/agent/instructions

Replaces one exact string in the main agent's routing instructions with another, matching literally on whitespace, punctuation and case. Quote oldString from a read or search result; with replaceAll off, more than one match is an error rather than a guess.

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

oldString
string
required

The exact text to replace, copied verbatim from a read or search result. Matching is literal — whitespace, punctuation and case must match. Do not include the line numbers a read adds.

Minimum length: 1
newString
string
required

The text to put in its place. May be empty to delete.

replaceAll
boolean
default:false

Replace every occurrence. When false, more than one match is an error rather than a guess.

Response

200 - application/json

Returns how many occurrences were replaced in the main agent's instructions, a unified diff of the changed lines, the document's line count after the write, and any references or mentions the new text left unresolved.

message
string
required

A human-readable summary naming the lines that changed.

replacements
integer
required

How many occurrences were replaced.

Minimum: -9007199254740991 · Maximum: 9007199254740991
diff
string
required

A unified diff of the changed lines, with 1-based hunk headers.

totalLines
integer
required

How many lines the document has AFTER the write.

Minimum: -9007199254740991 · Maximum: 9007199254740991
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
unresolvedMentions
object[]

Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.

StableUnresolvedMention — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/agent/instructions/search

Searches the main agent's routing instructions line by line with a JavaScript regular expression and returns one page of matching lines with surrounding context, up to limit; the match totals count the whole document.

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

pattern
string
required

A JavaScript regular expression, evaluated against each line on its own.

Minimum length: 1 · Maximum length: 256
ignoreCase
boolean
default:false

Match case-insensitively. Defaults to false, like grep.

contextLines
integer
default:0

How many lines either side of each match to return.

Minimum: 0 · Maximum: 5
limit
integer
default:50

The maximum number of matching LINES to return. The reported totals cover the whole document.

Minimum: 1 · Maximum: 200

Response

200 - application/json

Returns the matching lines of the main agent's instructions, each with its line number, hit count and context lines, plus the total matches and matching lines across the whole document and whether the limit cut the list short.

matches
object[]
required
StableInstructionsSearchMatch — see its attributes above
totalMatches
integer
required

Total occurrences across the whole document, not just this page.

Minimum: -9007199254740991 · Maximum: 9007199254740991
matchingLines
integer
required

Total lines with at least one occurrence, across the whole document.

Minimum: -9007199254740991 · Maximum: 9007199254740991
hasMore
boolean
required

Whether matching lines were left out because of the limit.

Current - 2026/09
Endpoint
GET
/v2/stable/agent/prompt

Returns one page of the global prompt, each line prefixed with its 1-based number, so a later patch can quote text exactly as it appears. offset and limit pick the page; the totals in the response cover the whole prompt.

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

offset
integer
default:1

The 1-based line number to start from. Clamped to the last line of the document.

Minimum: 1 · Maximum: 9007199254740991
limit
integer
default:400

The maximum number of lines to return. A page is also capped at 24,000 characters, so a page of very long lines can come back shorter than this — follow nextOffset while hasMore is true.

Minimum: 1 · Maximum: 2000

Response

200 - application/json

Returns the requested lines of the global prompt as one numbered block, with the page's actual offset, its line count, the prompt's total lines and characters, and whether more lines follow.

content
string
required

The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.

offset
integer
required

The line number this page actually starts at, after clamping.

Minimum: -9007199254740991 · Maximum: 9007199254740991
returnedLines
integer
required

How many lines this page carries.

Minimum: -9007199254740991 · Maximum: 9007199254740991
totalLines
integer
required

How many lines the whole document has.

Minimum: -9007199254740991 · Maximum: 9007199254740991
totalCharacters
integer
required

How many characters the whole document has.

Minimum: -9007199254740991 · Maximum: 9007199254740991
hasMore
boolean
required

Whether lines remain after this page.

nextOffset
integer
required

The first line not returned, or null when there is nothing more to read.

Minimum: -9007199254740991 · Maximum: 9007199254740991
note
string

Names the backticked names on this page that are links to a tool, playbook or workflow. A link reads as the resource's current name, whatever spelling the write used. Absent when the page shows no link.

Current - 2026/09
Endpoint
PATCH
/v2/stable/agent/prompt

Replaces one exact string in the global prompt with another, matching literally on whitespace, punctuation and case. Quote oldString from a read or search result; with replaceAll off, more than one match is an error rather than a guess.

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

oldString
string
required

The exact text to replace, copied verbatim from a read or search result. Matching is literal — whitespace, punctuation and case must match. Do not include the line numbers a read adds.

Minimum length: 1
newString
string
required

The text to put in its place. May be empty to delete.

replaceAll
boolean
default:false

Replace every occurrence. When false, more than one match is an error rather than a guess.

Response

200 - application/json

Returns how many occurrences were replaced in the global prompt, a unified diff of the changed lines, the prompt's line count after the write, and any references or mentions the new text left unresolved.

message
string
required

A human-readable summary naming the lines that changed.

replacements
integer
required

How many occurrences were replaced.

Minimum: -9007199254740991 · Maximum: 9007199254740991
diff
string
required

A unified diff of the changed lines, with 1-based hunk headers.

totalLines
integer
required

How many lines the document has AFTER the write.

Minimum: -9007199254740991 · Maximum: 9007199254740991
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
unresolvedMentions
object[]

Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.

StableUnresolvedMention — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/agent/prompt/search

Searches the global prompt line by line with a JavaScript regular expression and returns one page of matching lines with surrounding context, up to limit; the match totals count the whole prompt.

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

pattern
string
required

A JavaScript regular expression, evaluated against each line on its own.

Minimum length: 1 · Maximum length: 256
ignoreCase
boolean
default:false

Match case-insensitively. Defaults to false, like grep.

contextLines
integer
default:0

How many lines either side of each match to return.

Minimum: 0 · Maximum: 5
limit
integer
default:50

The maximum number of matching LINES to return. The reported totals cover the whole document.

Minimum: 1 · Maximum: 200

Response

200 - application/json

Returns the matching lines of the global prompt, each with its line number, hit count and context lines, plus the total matches and matching lines across the whole prompt and whether the limit cut the list short.

matches
object[]
required
StableInstructionsSearchMatch — see its attributes above
totalMatches
integer
required

Total occurrences across the whole document, not just this page.

Minimum: -9007199254740991 · Maximum: 9007199254740991
matchingLines
integer
required

Total lines with at least one occurrence, across the whole document.

Minimum: -9007199254740991 · Maximum: 9007199254740991
hasMore
boolean
required

Whether matching lines were left out because of the limit.

Endpoint
POST
/v1/stable/agent/tool-message

Gives one of the agent's tools a message in a slot that has none yet, either generative (examples the model writes from) or scripted (an existing response said verbatim). Address a built-in tool with nativeTool or an attached tool with toolID, and compile the environment afterward.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

environmentAlias
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

slot
object
required

Which of the tool's four messages to write. execution is said when the tool starts (the editor labels it Start), completion when it finishes (Complete), failure when it errors (Failed), delay when it is taking a while (Delayed).

Available options: delay, failure, execution, completion
StableToolMessageSlot — see its attributes above
toolID
string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Minimum length: 1
nativeTool
object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Request body

A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.

Response

200 - application/json

Confirms the message was set and which form, generative or scripted, the slot is now in.

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
PATCH
/v1/stable/agent/tool-message

Replaces the message in a slot that already has one, with the full set of examples or the response to say instead. Switching between generative and scripted keeps the stored text of the form you switched away from, switched off.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

environmentAlias
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

slot
object
required

Which of the tool's four messages to write. execution is said when the tool starts (the editor labels it Start), completion when it finishes (Complete), failure when it errors (Failed), delay when it is taking a while (Delayed).

Available options: delay, failure, execution, completion
StableToolMessageSlot — see its attributes above
toolID
string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Minimum length: 1
nativeTool
object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Request body

A tool message in one of its two forms. Writing one form switches the slot to it and leaves the other form stored but inactive, exactly as the editor does — so switching back does not have to be retyped.

Response

200 - application/json

Confirms the message was replaced and which form, generative or scripted, the slot is now in.

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
DELETE
/v1/stable/agent/tool-message

Clears one message slot on one of the agent's tools, discarding its examples and unlinking its scripted response. The response carries only a confirmation message, so refetch the agent's tool to see its remaining messages.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

environmentAlias
string
required

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

slot
object
required

Which of the tool's four messages to write. execution is said when the tool starts (the editor labels it Start), completion when it finishes (Complete), failure when it errors (Failed), delay when it is taking a while (Delayed).

Available options: delay, failure, execution, completion
StableToolMessageSlot — see its attributes above
toolID
string

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Minimum length: 1
nativeTool
object

Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.

Response

200 - application/json

Confirms the message in the requested slot was removed.

message
string
required

A human-readable message confirming the deletion.

Endpoint
PATCH
/v1/stable/agent/pronunciation

Edits single entries of the voice pronunciation dictionary, a list of written words and how the voice says them. set adds words or replaces the entry for a word already stored, remove deletes every entry for a word, and words match ignoring letter case.

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

set
object[]

Words to add, or to change when the dictionary already has them. from is the written word and to is how the voice says it; an empty to makes the voice skip the word.

Minimum items: 1 · Maximum items: 500
PronunciationDictionaryEntry — see its attributes above
remove
string[]

Written words whose entries to delete.

Minimum items: 1 · Maximum items: 500

Response

200 - application/json

Returns how many entries were added, changed and removed, the words in remove the dictionary did not have, and how many entries the dictionary holds now.

message
string
required

A human-readable message confirming the update.

added
integer
required

How many new words the dictionary gained.

Minimum: -9007199254740991 · Maximum: 9007199254740991
replaced
integer
required

How many stored words got the pronunciation this call sent.

Minimum: -9007199254740991 · Maximum: 9007199254740991
removed
integer
required

How many entries were deleted.

Minimum: -9007199254740991 · Maximum: 9007199254740991
notFound
string[]
required

Words in remove the dictionary did not have. Nothing was deleted for them.

totalEntries
integer
required

How many entries the dictionary holds now.

Minimum: -9007199254740991 · Maximum: 9007199254740991
Endpoint
GET
/v1/stable/agent/voice-catalog

Search the ElevenLabs and Cartesia voice catalog.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Query parameters

projectID
string
required

The ID of the project to operate on.

Words to find in the name, description or accent, or one whole voice ID. Every word must match, ignoring case: "vikram" or "calm british".

Minimum length: 1 · Maximum length: 200
language
string

Only voices that speak this language: a language ("hi") or a language and region ("en-IN"). Native speakers come first, and with a region those native to it before the rest.

Minimum length: 2 · Maximum length: 35
provider
object
gender
object
limit
integer
default:10

The most voices to return in one page.

Minimum: 1 · Maximum: 25
offset
integer
default:0

How many matching voices to skip: nextOffset from the previous page.

Minimum: 0 · Maximum: 9007199254740991

Response

200 - application/json
voices
object[]
required

This page of the matching voices, best match first.

StableCatalogVoice — see its attributes above
total
integer
required

How many voices match, across every page.

Minimum: -9007199254740991 · Maximum: 9007199254740991
nextOffset
integer
required

The offset of the next page, or null when this page reaches the last match.

Minimum: -9007199254740991 · Maximum: 9007199254740991
Endpoint
PATCH
/v1/stable/agent/voices

Set the agent's default voice, or add, change or remove one language voice, from the voice catalog.

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

primary
object

The default voice: the one a conversation speaks with unless a language voice matches its locale.

setOverrides
object[]

Language voices to add, or to change when the agent already has one for that locale.

Minimum items: 1 · Maximum items: 50
StableVoiceOverridePick — see its attributes above
removeOverrides
string[]

Locales whose language voice to delete, as stored. They match ignoring case and _, as the runtime matches them.

Minimum items: 1 · Maximum items: 50

Response

200 - application/json
message
string
required

A human-readable message confirming the update.

added
string[]
required

Locales that got a language voice they did not have.

replaced
string[]
required

Locales whose language voice changed.

removed
string[]
required

Locales whose language voice was deleted.

notFound
string[]
required

Locales in removeOverrides the agent had no language voice for. Nothing was deleted for them.

Endpoint
GET
/v1/stable/agent/initialization-workflow

Returns the agent's initialization workflow, the workflow set in Behaviour settings that runs at launch, before the user says anything. The name is null when the ID points at a workflow that no longer exists.

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 the ID and name of the initialization workflow, both null when none is set or when the project has no initialization workflow setting.

workflowID
string
required

The workflow that runs before the user's first turn, or null when none is set or this project has no initialization workflow setting.

name
string
required

That workflow's name. Null when none is set, or when the stored ID names a workflow that no longer exists.

Endpoint
PUT
/v1/stable/agent/initialization-workflow

Sets which workflow the agent runs at launch, replacing the one set before, or clears the setting when workflowID is null. Only a workflow ID from the workflow list is accepted, and compiling the environment is what makes a test conversation use it.

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

workflowID
string
required

The workflow to run before the user's first turn, or null to run none.

Minimum length: 1

Response

200 - application/json

Confirms which workflow now runs before the user's first turn, or that none does, and names the workflow it replaced when there was one.

message
string
required

A human-readable message confirming the update.

Schemas

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