Voiceflow bearer token
Workflows
Define the steps your agent follows.
See Authentication for credentials and permissions.
Returns a page of the environment's workflows with the IDs the other workflow operations take. A workflow is a graph of blocks and steps the agent can run; send nextCursor as cursor for the next page.
Authentication
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Only the workflows in this folder.
The nextCursor of the previous page. Leave it out for the first page. Pages are counted on the workflows as they are at each call, so an edit between pages can repeat or skip a workflow.
The most workflows to return. Defaults to 50.
Response
Returns a page of workflows with each one's ID, name, description, folder and last update time. When more follow, nextCursor holds the value to send as cursor for the next page.
Present when more workflows follow. Send it as cursor.
Builds a whole workflow in one request, including its blocks, steps, branches and the links between blocks. The new workflow is not reachable by the agent until you add it to the agent's workflows and write a routing rule for 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
Response
Returns the new workflow's ID, its entry step, a map from each key you sent to the ID the server created, and any warnings or unresolved references.
Every key in the request, mapped to the ID the server created.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Reads a workflow as blocks of steps, each with its kind, content and links. Messages and prompts appear as IDs, not their text. Read it before any edit to get the block and step IDs.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The truncated.nextCursor of the previous page. Leave it out for the first page. Pages are counted on the workflow as it is at each call, so an edit between pages can repeat or skip a block.
Response
Returns the workflow's name, description and counts, then a page of its blocks. When there are more blocks, truncated.nextCursor holds the value to send as cursor for the next page.
At most 50 blocks: breadth-first from the start, then blocks nothing reaches.
Present when more blocks follow. Send nextCursor as cursor to read the next page.
Changes a workflow's name, description or folder. It does not edit blocks or steps; use the block and step operations for that.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
A workflow folder in this environment, or null for the top level.
Response
Confirms the workflow was updated. Only a confirmation message comes back, so refetch the workflow to see its new values.
A human-readable message confirming the update.
Removes the workflow from the environment. The agent's routing can still name it, so check the agent's rules. The response carries only a confirmation message, so refetch the workflows to see what is left.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Confirms the workflow was deleted. Only a confirmation message comes back.
A human-readable message confirming the deletion.
Reads a single step without fetching the whole workflow. An action ID from an exit's actions reads the same way.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Returns the step's kind, content, exit class and links, along with the block it is in.
The block the step is in, or null for a port action or a step no block lists.
Edits a step's settings, or points it at a different message or prompt. To change the words a step says, update its message or prompt instead. Branches have their own operations.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Response
Confirms the step was updated. Returns what was written, the block that holds the step, and the step with its new content.
What was written.
The block that holds the step, or null for a step that no block lists.
Set when the step is an action on an exit: the step and port that run it, and its position.
Each key you sent on the step or its branches, mapped to the ID the server created.
Links this write cleared because they would no longer run.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Removes one step, or one action from an exit when you pass an action ID; it is removed from the block it sat in. Send expectedSteps as your last read returned them. The response lists the links that were cleared and the links that now run.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The block's step IDs exactly as your last read returned them, in order, as an array: ["m1", "e1"]. For an action, the action IDs of its exit. If they changed, nothing is written.
Response
Confirms the step was deleted. Returns what was removed, the links that were cleared, and the links that now run.
What was deleted.
Exits of the steps that remain whose path led to a removed block or step. Each is now unlinked. An exit whose actions led there is named by its step and port.
Hidden links of a step that became the last step of its block. They did not run before the delete and run now, as on the canvas.
Returns the workflow's canvas nodes as they are stored, with real coordinates, as a map keyed by node ID. Pass blockIDs to narrow the read to some blocks; it is larger than the standard workflow read, so use it only when that read cannot answer.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to read.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Read only these blocks, or the Start step ID, with their steps and the actions on their exits, as an array: ["blk_1", "blk_2"]. Leave it out to read every node.
Response
Returns the workflow's ID, name and canvas ID, the stored nodes by ID with rich text rendered as strings, and any requested block IDs that matched no block.
The stored nodes by ID: blocks, steps, the Start and action lists. A block lists its step IDs in data.steps, and ports keep their targets in data.portsV2. Text the canvas stores as rich text reads as a string, with {name} for a variable, entity or secret and name for a tool, playbook or workflow. Every other field is exactly as stored, and its shape can change without notice.
IDs in blockIDs that name no block or Start in this workflow.
Copies a workflow under the name you give. The copy gets its own copies of the messages, prompts, playbooks and Operator agents its steps use, while block and step IDs stay the same.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to copy.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The name of the copy.
Response
Returns a message, the new workflow's ID and name, and maps from each original message, prompt, playbook and Operator agent ID to the ID of its copy.
The copy.
The original ID of each copied resource, mapped to the ID of its copy. Block and step IDs do not change.
Legacy - 2026/10
Wires an exit of a step to a block, replacing whatever the port led to before. Links point at blocks, not steps.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The port to operate on: next, fail, else, no-reply, or the ID of a branch.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The block the port will lead to. Links point at blocks, never at a step inside one.
Response
Confirms the new link. Returns the link with its step, port and the block it now leads to.
Disconnects an exit so the path stops there. No step or block is deleted, and any actions on the exit stay.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The port to operate on: next, fail, else, no-reply, or the ID of a branch.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Confirms the port now leads nowhere. Returns the link with its step and port; a port that already led nowhere is reported as such and nothing is written.
Current - 2026/10
Wires an exit of a step to a block, replacing whatever the port led to before. If other edits keep changing the workflow while the call saves, it returns 409 and writes nothing; read the workflow again and resend.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The port to operate on: next, fail, else, no-reply, or the ID of a branch.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The block the port will lead to. Links point at blocks, never at a step inside one.
Response
Confirms the new link. Returns a message and the link; when a link was replaced, replacedLink and the message name the block the port led to before.
Present when the port already led to another block: the link this call replaced.
Points up to 50 ports at blocks in one write. Every link is checked before anything is saved, and they save together; a port that led elsewhere now leads to the new block and keeps its actions.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow that holds the ports.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
1 to 50 ports to link, each once.
Response
Returns a message and, for each port in the order sent, the block it led to before.
What was written.
Every port in the order you sent them, with the block it led to before.
Legacy - 2026/10
Adds a block of 1 to 20 steps to an existing workflow, placed next to placement.afterBlockID. When you send from, the call also links that port to the new block.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Place the new block to the right of this block. Without it, the block goes next to the block of from.stepID, or right of the right-most block.
Also link this port to the new block in the same call, with the same checks as voiceflow_workflow.link.
Response
Returns the new block with its steps, a map from each key you sent to the ID the server created, and any unresolved references.
Every key in the request, mapped to the ID the server created.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Current - 2026/10
Adds a block of 1 to 20 steps to an existing workflow, placed next to placement.afterBlockID. When you send from, the call also links that port to the new block and replaces the block that port led to. If other edits keep changing the workflow while the call saves, it returns 409 and writes nothing.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Place the new block to the right of this block. Without it, the block goes next to the block of from.stepID, or right of the right-most block.
Also link this port to the new block in the same call, with the same checks as voiceflow_workflow.link.
Response
Returns a message, the new block with its steps, a map from each key you sent to the ID the server created, and any unresolved references. When a link was replaced, replacedLink names the block the port led to before.
Every key in the request, mapped to the ID the server created.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Present when from already led to another block: the link this call replaced.
Creates up to 20 blocks with their steps in one write, links them to each other and to existing blocks, and can link existing ports to them. The server places the new blocks, so the request carries no coordinates.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to add the blocks to.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The new blocks. A step's links and a branch's to name a block key from this call or an existing block ID.
Existing ports to link to new blocks in the same call, with the same checks as voiceflow_workflow.link.
Place the new blocks to the right of this block. Without it, they go right of the block of the first from step, or right of the right-most block.
Response
Returns a message, the new blocks, a map from each request key to the ID created for it, the existing ports that were linked with what each led to before, and any references that could not be resolved.
What was written.
Every key in the request, mapped to the ID the server created.
The from ports, each with the block it led to before.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Changes a block's name or color. Its steps and links stay as they are.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the block to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Response
Confirms the block was updated. Only a confirmation message comes back, so refetch the workflow to see the new values.
A human-readable message confirming the update.
Deletes a whole block, which is removed from the workflow with the links into it. Send expectedSteps as your last read returned them, so a changed block is not deleted by mistake. The response lists the links that were cleared and the links that now run.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the block to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
The block's step IDs exactly as your last read returned them, in order, as an array: ["m1", "e1"]. For an action, the action IDs of its exit. If they changed, nothing is written.
Response
Confirms the block was deleted. Returns what was removed, the links into it that were cleared, and the links that now run.
What was deleted.
Exits of the steps that remain whose path led to a removed block or step. Each is now unlinked. An exit whose actions led there is named by its step and port.
Hidden links of a step that became the last step of its block. They did not run before the delete and run now, as on the canvas.
Moves blocks into columns by their links, starting from the Start block, with blocks stacked by height. Pass blockIDs to move only those blocks; otherwise every block moves except the Start. Steps, links and names are not changed.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow whose blocks to arrange.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Move only these blocks, as a group laid out by the links between them. Leave it out to arrange every block from the Start.
Response
Returns a message and the blocks that moved, each with its new position.
What was written.
Each block that moved, with its new position.
Divides one block into two at a step you choose, so a link can enter at that step or a step can branch. Send expectedSteps as your last read returned them; if the block changed since then, the call returns 409 and writes nothing.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the block to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The step that starts the new block. It and every step below it move there, and the step above it becomes the last step of the block. To make step X the last step, so that its fail and path ports run, send the step below X. It must not be the first step.
The new block name. Default: the block name with " (continued)".
The block's step IDs exactly as your last read returned them. If the block changed, nothing is written.
Required when the step that becomes the last step has hidden links or actions. The split keeps them, so they start to run. An action list on its next exit is deleted, because next links to the new block.
Response
Returns both blocks, head for the part that keeps the original ID and tail for the new one. Link a port to the tail block next.
Actions on the next exit of the head’s new last step that were deleted, because next now links to the new block. Its hidden links are kept and now run.
Adds a step to a block, either after a step you name or at the start of the block. Send expectedSteps as your last read returned them; if the block changed since then, the call returns 409 and writes nothing.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the block to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Insert right after this step of the block. Send this or atStart.
Insert as the first step of the block. Send this or afterStepID.
trueThe block's step IDs exactly as your last read returned them. If the block changed, nothing is written.
Required when the insert makes the last step stop being last and that step has exits that would stop running: a Tool or Code fail or path link is cleared, and actions on such an exit are deleted. Also required when you append a step that has no next port, such as End or Go to block: the old last step's next link cannot move to it, so it is cleared.
Response
Returns what was written, the block that holds the new step, the step itself, and the IDs the server created.
What was written.
The block that holds the step, or null for a step that no block lists.
Set when the step is an action on an exit: the step and port that run it, and its position.
Each key you sent on the step or its branches, mapped to the ID the server created.
Links this write cleared because they would no longer run.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Gives a Condition, Buttons, Card, Carousel, Code or Crew step one more way out. When you send to, the call also links the new branch to a block.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Response
Returns the new branch's ID, which is also its port key, and the step with the branch added.
What was written.
The branch ID. It is also the port key that link and unlink take.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Edits a branch's label, assertions, URL or exit path details. The branch keeps its link; use the link operation to repoint it. assertions replaces the branch's whole list of checks.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The ID of the branch to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Response
Returns what was written, the branch ID, and the step with the branch's new content.
What was written.
The branch ID. It is also the port key that link and unlink take.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Removes a branch from a step together with its port and link. Removing the last path of a Condition also removes its else port.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The ID of the branch to operate on.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Response
Confirms the branch was deleted. Only a confirmation message comes back.
A human-readable message confirming the deletion.
Adds port actions to one exit of a step. They run in order when the conversation leaves through that exit, before the path reaches the next block. Add 1 to 10 at a time, and send the exit's current action IDs as expectedActions.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The port to operate on: next, fail, else, no-reply, or the ID of a branch.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
1 to 10 actions to add, in run order.
Add them after this action. Leave out afterActionID and atStart to add them at the end, before an action that ends the path.
Add them before every other action on this exit.
trueThe IDs in this exit's actions from your last read, in order. Send [] when it has none.
The block the path goes to after the actions. Leave it out to keep the current one. Send null to clear it.
Response
Returns what was written, the exit's step and port, and its link. If the last action ends the path, clearedTo names the block the exit led to before.
What was written.
The step that owns the exit, or the start node.
The block the exit continued to before this write. Dropped because the actions now end the path.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.
Sets a new running order for the actions on an exit. Send every action ID of the exit; the path still continues to the same block afterward.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow to operate on.
The ID of the step to operate on.
The port to operate on: next, fail, else, no-reply, or the ID of a branch.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
Every action ID of this exit, in the new order.
Response
Returns what was written, the exit's step and port, the action IDs in their new order, and the block the path reaches after them.
What was written.
The action IDs in their new order.
The block the path reaches after the actions. Reordering keeps it.
Replaces one action on a block exit with a new action of any kind, keeping its place in the run order. The new action gets a new ID, and an action that ends the path drops the link the exit had.
Authentication
Voiceflow bearer token
Path parameters
The ID of the workflow that holds the action.
The ID of the action to replace.
Query parameters
The ID of the project to operate on.
The alias of the environment to operate on (e.g. main).
Request body
The IDs in this exit's actions from your last read, in order.
Response
Returns a message, the step and port that own the exit, the resulting link, the block the exit led to before if the new action ended the path, and any unresolved references.
What was written.
The step that owns the exit, or the start node.
The block the exit continued to before this write. Dropped because the actions now end the path.
References this write kept as literal text instead of binding, each with the reason. The write still succeeded.