Update a playbook

import requests
url = "https://example.ada.support/api/v2/playbooks/65a17e3f43bec88e2792d0eb"
payload = {
    "description": "How to process a refund for an order placed in the last 30 days",
    "enabled": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())

{
  "id": "65a17e3f43bec88e2792d0eb",
  "name": "Refund flow",
  "version": 2,
  "enabled": true,
  "description": "How to process a refund for an order placed in the last 30 days",
  "general_instructions": "Confirm the order number before issuing a refund.",
  "sections": [
    {
      "id": "5df263b7db5a7e6ea03fae9b",
      "title": "Main",
      "steps": [
        {
          "id": "5df263b7db5a7e6ea03faea0",
          "type": "send",
          "message": "Let me pull up that order."
        }
      ]
    }
  ],
  "can_run_standalone": true,
  "referenced_articles": [],
  "tags": [],
  "acknowledgment_instruction": "Let me look into that for you",
  "chat_acknowledgment_override": false,
  "on_human_request": "exit_playbook",
  "on_off_topic": "exit_playbook",
  "on_off_script": "search_knowledge",
  "availability_rules": null
}

Partially update a version 2 playbook in place (same id). Only the fields present in the body change; omit enabled to leave the active state unchanged. Setting enabled to true validates the full step graph and activates the playbook.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

playbook_idstringRequired

The id of the playbook

Request

This endpoint expects an object.

namestringOptional1-128 characters

Display name for the playbook

descriptionstringOptional<=512 characters

Short description of the playbook (routing-facing). Required to be non-empty when the playbook is active; activating one without a description is rejected with 422.

sectionslist of objectsOptional

The ordered sections of the playbook. Each section holds an ordered list of steps (send, set, ask, run, if_else, go_to). Every section and step needs a caller-generated unique ObjectId string. Editing sections is rejected with 422 on a Playbook that has send-step attachments. Add or edit those in the dashboard. Every other field stays editable through the API.

enabledbooleanOptional

Set the playbook's active state. Omit to leave it unchanged. Setting true validates the full step graph before activating.

general_instructionsstring or nullOptional

Instructions that apply across the whole playbook. Send null to clear.

on_human_requestenumOptional

Deviation behavior when the user asks for a human

on_off_topicenumOptional

Deviation behavior when the user goes off topic

on_off_scriptenumOptional

Deviation behavior when the conversation goes off script

acknowledgment_instructionstring or nullOptional<=500 characters

Instruction for the acknowledgment message

chat_acknowledgment_overridebooleanOptional

Request an acknowledgment for this playbook on messaging platforms even when the Agent-wide messaging acknowledgment setting (enable_acknowledgment_messages) is off. Never suppresses.

availability_rulesobject or nullOptional

Omit to leave the current rule unchanged, send null to clear it, or send a rule to replace it. An unknown variable id or a malformed rule is rejected with a 400.

Response

idstringRead-only

The unique identifier for the playbook

namestring<=128 characters

Display name for the playbook

versionintegerRead-only=2

The playbook schema version. Always 2 on this surface.

enabledboolean

Whether the playbook is enabled. False means draft.

descriptionstringOptional

Short description of the playbook (routing-facing)

general_instructionsstring or nullOptional

Instructions that apply across the whole playbook

sectionslist of objects or nullOptionalRead-only

The ordered sections of the playbook. Each section holds an ordered list of steps (send, set, ask, run, if_else, go_to).

can_run_standalonebooleanOptional

Whether the playbook can be triggered on its own

referenced_articleslist of stringsOptional

Ids of knowledge articles referenced by the playbook

tagslist of stringsOptional

Tag ids applied to the playbook

acknowledgment_instructionstring or nullOptional<=500 characters

Instruction for the acknowledgment message

chat_acknowledgment_overridebooleanOptional

Request an acknowledgment for this playbook on messaging platforms even when the Agent-wide messaging acknowledgment setting (enable_acknowledgment_messages) is off. Never suppresses.

on_human_requestenumOptional

Deviation behavior when the user asks for a human

on_off_topicenumOptional

Deviation behavior when the user goes off topic

on_off_scriptenumOptional

Deviation behavior when the conversation goes off script

availability_rulesobject or nullOptionalRead-only

The structured rule that gates when the Agent uses this Playbook, with variables referenced by id, or null when no rule is attached

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

409

Conflict Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error