> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.ada.cx/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.ada.cx/_mcp/server. # Playbooks API The Playbooks API provides full create, read, update, and delete access to your AI Agent's [Playbooks](/docs/automation/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. Download full OpenAPI spec 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)](/docs/automation/playbooks/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](/reference/introduction/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](/docs/automation/playbooks/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](/reference/introduction/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](/reference/introduction/authentication) for details on generating and using API keys.