Voiceflow bearer token
Agents
Create and configure your agents.
See Authentication for credentials and permissions.
Legacy - 2026/07
Returns the environment’s agent: the global prompt, the instructions that route a turn, and the settings wrapping both.
Authentication
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
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.
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
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.
Legacy - 2026/07
Changes the agent that shapes every turn - its global prompt, its routing instructions, or its settings - in the environment named by the request.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Markdown text. Backticked Name resolves to a tool, playbook, or workflow reference; braced {name} resolves to a variable or entity reference. Tokens that do not resolve are stored as literal text and reported back in the response.
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 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.
Markdown text. Backticked Name resolves to a tool, playbook, or workflow reference; braced {name} resolves to a variable or entity reference. Tokens that do not resolve are stored as literal text and reported back in the response.
The ordered list of path tool IDs that controls the order of the agent exit paths.
Whether to append the default prompting guidelines to the global prompt.
Response
Confirms the agent's configuration was updated. The body is a message rather than the new configuration, so read the agent back to see its current prompt, instructions, and tool settings.
A human-readable message confirming the update.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
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.
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
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.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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 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.
The ordered list of path tool IDs that controls the order of the agent exit paths.
Whether to append the default prompting guidelines to the global prompt.
Response
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.
A human-readable message confirming the update.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The 1-based line number to start from. Clamped to the last line of the document.
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.
Response
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.
The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.
The line number this page actually starts at, after clamping.
How many lines this page carries.
How many lines the whole document has.
How many characters the whole document has.
Whether lines remain after this page.
The first line not returned, or null when there is nothing more to read.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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.
The text to put in its place. May be empty to delete.
Replace every occurrence. When false, more than one match is an error rather than a guess.
Response
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.
A human-readable summary naming the lines that changed.
How many occurrences were replaced.
A unified diff of the changed lines, with 1-based hunk headers.
How many lines the document has AFTER the write.
Braced {name} tokens anywhere in the document AFTER the patch that matched no variable or entity and were stored as literal text. The whole document is resolved, so a token the patch did not touch is reported too.
Backticked names anywhere in the document AFTER the patch that matched no attached tool, playbook or workflow. The whole document is resolved, so a name the patch did not touch is reported too.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The 1-based line number to start from. Clamped to the last line of the document.
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.
Response
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.
The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.
The line number this page actually starts at, after clamping.
How many lines this page carries.
How many lines the whole document has.
How many characters the whole document has.
Whether lines remain after this page.
The first line not returned, or null when there is nothing more to read.
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
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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.
The text to put in its place. May be empty to delete.
Replace every occurrence. When false, more than one match is an error rather than a guess.
Response
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.
A human-readable summary naming the lines that changed.
How many occurrences were replaced.
A unified diff of the changed lines, with 1-based hunk headers.
How many lines the document has AFTER the write.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
A JavaScript regular expression, evaluated against each line on its own.
Match case-insensitively. Defaults to false, like grep.
How many lines either side of each match to return.
The maximum number of matching LINES to return. The reported totals cover the whole document.
Response
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.
Total occurrences across the whole document, not just this page.
Total lines with at least one occurrence, across the whole document.
Whether matching lines were left out because of the limit.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
A JavaScript regular expression, evaluated against each line on its own.
Match case-insensitively. Defaults to false, like grep.
How many lines either side of each match to return.
The maximum number of matching LINES to return. The reported totals cover the whole document.
Response
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.
Total occurrences across the whole document, not just this page.
Total lines with at least one occurrence, across the whole document.
Whether matching lines were left out because of the limit.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The 1-based line number to start from. Clamped to the last line of the document.
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.
Response
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.
The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.
The line number this page actually starts at, after clamping.
How many lines this page carries.
How many lines the whole document has.
How many characters the whole document has.
Whether lines remain after this page.
The first line not returned, or null when there is nothing more to read.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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.
The text to put in its place. May be empty to delete.
Replace every occurrence. When false, more than one match is an error rather than a guess.
Response
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.
A human-readable summary naming the lines that changed.
How many occurrences were replaced.
A unified diff of the changed lines, with 1-based hunk headers.
How many lines the document has AFTER the write.
Braced {name} tokens anywhere in the document AFTER the patch that matched no variable or entity and were stored as literal text. The whole document is resolved, so a token the patch did not touch is reported too.
Backticked names anywhere in the document AFTER the patch that matched no attached tool, playbook or workflow. The whole document is resolved, so a name the patch did not touch is reported too.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The 1-based line number to start from. Clamped to the last line of the document.
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.
Response
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.
The requested lines, each as its 1-based number, a tab, then the text, joined by newlines.
The line number this page actually starts at, after clamping.
How many lines this page carries.
How many lines the whole document has.
How many characters the whole document has.
Whether lines remain after this page.
The first line not returned, or null when there is nothing more to read.
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
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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.
The text to put in its place. May be empty to delete.
Replace every occurrence. When false, more than one match is an error rather than a guess.
Response
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.
A human-readable summary naming the lines that changed.
How many occurrences were replaced.
A unified diff of the changed lines, with 1-based hunk headers.
How many lines the document has AFTER the write.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Backticked name mentions that matched no attached tool, playbook or workflow and were stored as inline code. The write still succeeded.
Legacy - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
A JavaScript regular expression, evaluated against each line on its own.
Match case-insensitively. Defaults to false, like grep.
How many lines either side of each match to return.
The maximum number of matching LINES to return. The reported totals cover the whole document.
Response
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.
Total occurrences across the whole document, not just this page.
Total lines with at least one occurrence, across the whole document.
Whether matching lines were left out because of the limit.
Current - 2026/09
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
A JavaScript regular expression, evaluated against each line on its own.
Match case-insensitively. Defaults to false, like grep.
How many lines either side of each match to return.
The maximum number of matching LINES to return. The reported totals cover the whole document.
Response
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.
Total occurrences across the whole document, not just this page.
Total lines with at least one occurrence, across the whole document.
Whether matching lines were left out because of the limit.
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.
Authentication
Voiceflow bearer token
Query parameters
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
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).
delay, failure, execution, completionAddresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
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
Confirms the message was set and which form, generative or scripted, the slot is now in.
A human-readable message confirming the update.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
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.
Authentication
Voiceflow bearer token
Query parameters
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
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).
delay, failure, execution, completionAddresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
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
Confirms the message was replaced and which form, generative or scripted, the slot is now in.
A human-readable message confirming the update.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
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.
Authentication
Voiceflow bearer token
Query parameters
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
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).
delay, failure, execution, completionAddresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
Addresses one message on one tool. Exactly one of toolID and nativeTool is required; sending neither or both is rejected.
Response
Confirms the message in the requested slot was removed.
A human-readable message confirming the deletion.
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
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.
Written words whose entries to delete.
Response
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.
A human-readable message confirming the update.
How many new words the dictionary gained.
How many stored words got the pronunciation this call sent.
How many entries were deleted.
Words in remove the dictionary did not have. Nothing was deleted for them.
How many entries the dictionary holds now.
Search the ElevenLabs and Cartesia voice catalog.
Authentication
Voiceflow bearer token
Query parameters
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".
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.
The most voices to return in one page.
How many matching voices to skip: nextOffset from the previous page.
Response
This page of the matching voices, best match first.
How many voices match, across every page.
The offset of the next page, or null when this page reaches the last match.
Set the agent's default voice, or add, change or remove one language voice, from the voice catalog.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The default voice: the one a conversation speaks with unless a language voice matches its locale.
Language voices to add, or to change when the agent already has one for that locale.
Locales whose language voice to delete, as stored. They match ignoring case and _, as the runtime matches them.
Response
A human-readable message confirming the update.
Locales that got a language voice they did not have.
Locales whose language voice changed.
Locales whose language voice was deleted.
Locales in removeOverrides the agent had no language voice for. Nothing was deleted for them.
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Returns the ID and name of the initialization workflow, both null when none is set or when the project has no initialization workflow setting.
The workflow that runs before the user's first turn, or null when none is set or this project has no initialization workflow setting.
That workflow's name. Null when none is set, or when the stored ID names a workflow that no longer exists.
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.
Authentication
Voiceflow bearer token
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The workflow to run before the user's first turn, or null to run none.
Response
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.
A human-readable message confirming the update.