Get a playbook

import requests
url = "https://example.ada.support/api/v2/playbooks/65a17e3f43bec88e2792d0eb"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.json())

{
  "id": "65a17e3f43bec88e2792d0eb",
  "name": "Refund flow",
  "version": 2,
  "enabled": true,
  "description": "How to process a refund",
  "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
}

Retrieve a single version 2 playbook by its id

Authentication

AuthorizationBearer

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

Path parameters

playbook_idstringRequired

The id of the playbook

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

401

Unauthorized Error

404

Not Found Error

429

Too Many Requests Error

500

Internal Server Error