Voiceflow bearer token
Playbooks
Set goals and rules for your agent.
See Authentication for credentials and permissions.
Legacy - 2026/07
Returns every playbook in the environment. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The call takes no paging parameters, so one request yields the whole set.
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.
Response
Returns every playbook in the project environment, each with its name, description, instructions, model settings, and its own system tool configuration.
Legacy - 2026/07
Adds a playbook to the environment, a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries the ID that later calls address it by.
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 human-readable description of what the playbook does.
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.
Response
Returns the newly created playbook in full, including the ID assigned to it and the instructions it was created with.
Advisory naming any references in the submitted markdown that did not resolve.
Current - 2026/09
Returns every playbook in the environment. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The call takes no paging parameters, so one request yields the whole set, with each playbook's instructions as a plain Markdown string.
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.
Response
Returns every playbook in the project environment, each with its name, description, instructions, model settings, and its own system tool configuration.
Current - 2026/09
Adds a playbook to the environment, a set of instructions that drives an agent toward a goal, calling tools as it needs them. The instructions are sent as a plain Markdown string, and the response carries the ID that later calls address the playbook by.
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 human-readable description of what the playbook does.
Response
Returns the newly created playbook in full, including the ID assigned to it, and lists any references or mentions in its text that did not resolve.
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/07
Adds several playbooks to the environment in one request, each taking the fields the single-create call takes. The response carries the created playbooks in the same shape the list call returns.
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 playbooks the request created, as an array, each complete with the ID assigned to it.
Advisory naming any references in the submitted markdown that did not resolve.
Current - 2026/09
Adds several playbooks to the environment in one request, each taking the fields the single-create call takes. The response carries the created playbooks in the same shape the list call returns.
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 playbooks the request created, as an array, each complete with the ID assigned to it, and lists any references or mentions in their text that did not resolve.
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/07
Returns a single playbook by ID, with the fields that define it. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook to operate on.
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.
Response
Returns a single playbook, including its instructions, its tool ordering, and the system tool settings configured on it.
Legacy - 2026/07
Changes an existing playbook in place. The response carries only a confirmation message, so refetch the playbook to read its new values.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook 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 human-readable description of what the playbook does.
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.
Response
Confirms the playbook was updated. The response is a message, not the revised playbook, so fetch it again to read back the instructions or settings that changed.
A human-readable message confirming the update.
Deletes a single playbook by ID. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them. The response carries only a confirmation message, so refetch the playbooks to see what is left.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook 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 playbook was deleted from the project environment. The body is a message only, so list the playbooks again to see which remain.
A human-readable message confirming the deletion.
Current - 2026/09
Returns a single playbook by ID, with the fields that define it. A playbook is a set of instructions that drives an agent toward a goal, calling tools as it needs them, and its instructions come back as a plain Markdown string.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook to operate on.
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.
Response
Returns a single playbook, including its instructions, its tool ordering, and the system tool settings configured on it.
Current - 2026/09
Changes an existing playbook in place, with its instructions sent as a plain Markdown string. The response lists any references or mentions that did not resolve; read the playbook again to see its new values.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook 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 human-readable description of what the playbook does.
Response
Confirms the playbook was updated, and lists any references or mentions in the new text that did not resolve. The response is a message, not the revised playbook, so fetch it again to read back what changed.
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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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 a playbook's 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
Path parameters
The ID of the playbook 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 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 playbook'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.
Copy a playbook with its exit paths, messages and every tool but a workflow tool.
Authentication
Voiceflow bearer token
Path parameters
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. Leave it out to use the original's name with " copy" added.
Response
Where each copied tool and exit path went.
The original's workflow tools. The copy did not get them, because workflow tools go on the Main Agent only. The original keeps them.
Gives one of the playbook'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
Path parameters
The ID of the playbook to operate on.
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
Path parameters
The ID of the playbook to operate on.
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 playbook's tools, discarding its examples and unlinking its scripted response. The response carries only a confirmation message, so refetch the playbook's tool to see its remaining messages.
Authentication
Voiceflow bearer token
Path parameters
The ID of the playbook to operate on.
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.