Playbooks API

The Playbooks API provides full create, read, update, and delete access to your AI Agent’s Playbooks. Playbooks are the structured, step-based workflows that guide the Agent through multi-step conversations. Use the API to manage Playbooks in code and version control instead of only through the dashboard.

Each Playbook is identified by an id. It is either enabled (true) or disabled (false). An enabled Playbook is live. A disabled Playbook is a draft. New Playbooks default to draft, so creating one does not change the Agent’s behavior until you enable it.

This API serves Playbooks only. Playbooks (Classic) are not available through it, and a request for a Classic Playbook id returns 404.

Endpoints

Five endpoints are available:

List Playbooks (GET /v2/playbooks/): Returns the Agent’s Playbooks, enabled or not, in cursor-paginated pages ordered by id.
Create a Playbook (POST /v2/playbooks/): Creates a Playbook. New Playbooks default to draft (enabled: false). Set enabled: true to validate the full step graph and activate on create.
Get a Playbook (GET /v2/playbooks/{playbook_id}): Returns a single Playbook by its id.
Update a Playbook (PATCH /v2/playbooks/{playbook_id}): Partially updates a Playbook in place, keeping the same id. Only the fields in the request body change. Omit enabled to leave the live state unchanged.
Delete a Playbook (DELETE /v2/playbooks/{playbook_id}): Deletes a Playbook by its id.

Fields

Field	Type	Description
`id`	string	The unique identifier for the Playbook. Read-only.
`name`	string	Display name for the Playbook. Up to 128 characters. Required on create.
`description`	string	When to use this Playbook. Up to 512 characters. The Agent uses it to choose which Playbook to run, so an enabled Playbook must have one.
`version`	integer	The Playbook schema version. Always `2` on this surface. Read-only.
`enabled`	boolean	Whether the Playbook is live. Defaults to `false`, which means draft.
`sections`	array \| null	The ordered sections of the Playbook, each holding an ordered list of steps. Required on create, where an empty array is accepted for a draft. A draft that has never had sections set returns `null`.
`general_instructions`	string \| null	Guidance that applies across every section. Shown as General Guidelines in the dashboard. Send `null` to clear it.
`on_human_request`	string	Behavior when the end user asks for a human. One of `exit_playbook` or `stay_in_playbook`.
`on_off_topic`	string	Behavior when the end user goes off topic. One of `exit_playbook` or `stay_in_playbook`.
`on_off_script`	string	Behavior when the end user asks a knowledge question. One of `search_knowledge` or `skip_knowledge`.
`acknowledgment_instruction`	string \| null	Instruction for the acknowledgment message. Up to 500 characters.
`chat_acknowledgment_override`	boolean	Request an acknowledgment for this Playbook on messaging channels even when the Agent-wide acknowledgment setting is off. It never suppresses one.
`availability_rules`	object \| null	The rule that gates when the Agent uses this Playbook. `null` when no rule is set. See Availability rules.
`can_run_standalone`	boolean	Whether the Playbook can trigger on its own. Read-only on this API.
`referenced_articles`	array	Ids of the knowledge articles the Playbook references. Read-only on this API.
`tags`	array	Ids of the tags applied to the Playbook. Read-only on this API.

Sections and steps

sections holds the Playbook’s logic. Each section carries an id, a title, and an ordered list of steps. Sections are organizational. At runtime the Agent flattens them into a single queue and runs it top to bottom.

Six step types are available on this API: send, set, ask, run, if_else, and go_to. Read the step reference to see what each type does.

Supply your own unique ObjectId string as the id of every section and every step. Ids are stable per Playbook, so a go_to step can target another step by its id. An if_else branch holds its steps inline, and its conditions reference variables, not step ids.

A seventh step type, reason, is deprecated. Existing reason steps keep working. Create and update reject new ones with a 422.

Activation and validation

Setting enabled: true validates the whole Playbook before it goes live. The check covers:

the step graph, including go_to targets and if_else branches
variable scopes and condition operators
a non-empty name and description

A Playbook that fails validation is not saved. The response is a 422 that names the problem. A draft Playbook skips activation validation, so you can save work in progress.

An update that would make a Playbook reference itself through a chain of run steps returns 422.

Availability rules

An availability rule gates when the Agent uses a Playbook. Send a rule object to attach or replace one, null to clear it, or omit the field to leave it unchanged. availability_rules is null when no rule is set.

Deleting a Playbook also detaches its availability rule.

Rules reference variables by id. Look up the ids through the variables endpoint. An unknown variable id, a variable that cannot be used in a rule, or a malformed rule returns a 400. See Availability rules for the condition grammar and limits.

Playbooks with attachments

A Playbook can carry attachments on its send steps. Attachments cannot be authored through this API. A PATCH that sends sections on such a Playbook returns a 422. Edit its sections in the dashboard. Every other field stays editable through the API.

Pagination

The list endpoint is cursor-paginated. Use the limit query parameter to set the page size, from 1 to 100; omit it to use the default of 25. To page through results, read meta.next_page_url from the response and replay it unchanged to fetch the next page. next_page_url is null on the last or empty page.

Conflicts

Three situations return a 409 Conflict:

Enabled-Playbook limit: Enabling the Playbook would take the Agent past its limit of 100 live Playbooks.
Concurrent modification: Another change was saved to the Playbook between your read and your update. Read the Playbook again, then retry.
Playbook in use: A delete was blocked because another Playbook’s run step targets this one. Remove that reference first. A Playbook that references only itself stays deletable.

Not available through this API

Playbooks (Classic). Read and write Classic Playbooks in the dashboard.
Tags, standalone usage, and referenced articles. These are returned on read. Create and update reject them.
Timestamps and authorship. Created and updated times are not on this surface.

Authentication

Requests are authenticated with a Bearer API key. The read endpoints require the playbooks:read scope. Create, update, and delete require playbooks:write. See Authentication for details on generating and using API keys.