curl --request PATCH \ --url https://realtime-api.voiceflow.com/v2/stable/playbook/<playbookID>/instructions \ --header 'Authorization: Bearer <token>' --header 'Content-Type: application/json' \ --data '{ "oldString": "<string>", "newString": "<string>", "replaceAll": false }'

{ "message": "<string>", "replacements": 0, "diff": "<string>", "totalLines": 0, "unresolvedReferences": [ { "path": "<string>", "token": "<string>", "reason": "unknown" } ], "unresolvedMentions": [ { "path": "<string>", "mention": "<string>" } ] }

Authorizations

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

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.

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.

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.

unresolvedReferences

object[]

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

Show child attributes

path

string

required

Dotted path of the field that carried it, e.g. knowledgeBaseTool.filters[0].defaultValue.

token

string

required

The reference as written, without braces.

reason

enum<string>

required

unknown: no variable or entity of that name. secret-not-allowed: the name is a project secret and this field does not accept one. path-on-non-variable: only a variable has fields. resource-id: a bare resource id, not a name. invalid-name: outside the ^\w{1,64}$ name grammar. dangling: the reference rendered as a bare id, because its row is gone or its name is outside the name grammar.

Available options: unknown, secret-not-allowed, path-on-non-variable, resource-id, invalid-name, dangling

unresolvedMentions

object[]

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

Show child attributes

path

string

required

Dotted path of the markdown field that carried it, e.g. instructions or playbooks[3].instructions.

mention

string

required

The mention as written, without backticks.

Patch playbook instructions

Authorizations

Path Parameters

Query Parameters

Body

Response

TEXT