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

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.

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.

Response

200 - application/json

Returns every playbook in the project environment, each with its name, description, instructions, model settings, and its own system tool configuration.

playbooks
object[]
required
StablePlaybookReadV2 — see its attributes above
Current - 2026/09
Endpoint
POST
/v2/stable/playbook

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.

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

name
string
required
description
string

A human-readable description of what the playbook does.

instructions
object
endTool
object
cardTool
object
buttonTool
object
carouselTool
object
skipTurnTool
object
webSearchTool
object
callForwardTool
object
knowledgeBaseTool
object
settings
object

Response

201 - application/json

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.

playbook
object
required
StablePlaybookV2 — see its attributes above
unresolvedReferences
object[]

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

StableUnresolvedReference — see its attributes above
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/playbook/batch

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.

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

playbooks
object[]
required
StablePlaybookCreateRequestV2 — see its attributes above

Response

201 - application/json

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.

playbooks
object[]
required
StablePlaybookV2 — see its attributes above
unresolvedReferences
object[]

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

StableUnresolvedReference — see its attributes above
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
Endpoint
DELETE
/v1/stable/playbook/{playbookID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Response

200 - application/json

Confirms the playbook was deleted from the project environment. The body is a message only, so list the playbooks again to see which remain.

message
string
required

A human-readable message confirming the deletion.

Current - 2026/09
Endpoint
GET
/v2/stable/playbook/{playbookID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

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.

Response

200 - application/json

Returns a single playbook, including its instructions, its tool ordering, and the system tool settings configured on it.

playbook
object
required
StablePlaybookReadV2 — see its attributes above
Current - 2026/09
Endpoint
PATCH
/v2/stable/playbook/{playbookID}

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

name
string
settings
object
description
string

A human-readable description of what the playbook does.

instructions
object
endTool
object
cardTool
object
buttonTool
object
skipTurnTool
object
webSearchTool
object
callForwardTool
object
knowledgeBaseTool
object

Response

200 - application/json

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.

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/playbook/{playbookID}/instructions

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

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

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/playbook/{playbookID}/instructions

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

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

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/playbook/{playbookID}/instructions/search

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

Query parameters

projectID
string
required

The ID of the project to operate on.

environmentAlias
string
required

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

Request body

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

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/playbook/{playbookID}/duplicate

Copy a playbook with its exit paths, messages and every tool but a workflow tool.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

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

name
string

The name of the copy. Leave it out to use the original's name with " copy" added.

Minimum length: 1 · Maximum length: 255

Response

201 - application/json
playbook
object
required
StablePlaybookReadV2 — see its attributes above
ids
object
required

Where each copied tool and exit path went.

skippedWorkflowTools
string[]
required

The original's workflow tools. The copy did not get them, because workflow tools go on the Main Agent only. The original keeps them.

Endpoint
POST
/v1/stable/playbook/{playbookID}/tool-message

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

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/playbook/{playbookID}/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

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

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/playbook/{playbookID}/tool-message

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.

Request
Response

Authentication

Authorization
string
header
required

Voiceflow bearer token

Path parameters

playbookID
string
required

The ID of the playbook to operate on.

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.

Schemas

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