Skip to main content
Playbooks are reusable knowledge bundles you attach to agents. Wrapped by the Python SDK and Node SDK.

​
Endpoints at a glance

MethodPathSummary
GET/api/v1/playbooksList playbooks
POST/api/v1/playbooksCreate a custom playbook
GET/api/v1/playbooks/{id}Get a single playbook
PUT/api/v1/playbooks/{id}Update a playbook
DELETE/api/v1/playbooks/{id}Delete a custom playbook

​
Reference

​
GET /api/v1/playbooks

List playbooks Parameters
NameInTypeRequiredDescription
categoryquerystringNoFilter by category
searchquerystringNoPrefix search on name
limitqueryintegerNoPage size (1-100, default 10)
offsetqueryintegerNoPagination offset (default 0)
Responses
CodeDescriptionBody
200OKobject
400Missing X-Account-ID headerstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/playbooks \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/playbooks

Create a custom playbook Request body (application/json) Schema: handlers.CreatePlaybookRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
categorystringe.g. customer_support
descriptionstringe.g. Verify the order, check eligibility, then issue the refund via the payment processor.
display_namestringe.g. Refund Workflow
namestringe.g. refund_workflow
tagsarray<string>e.g. ['refunds', 'ecommerce']
tool_namesarray<string>e.g. ['lookup_order', 'verify_eligibility', 'issue_refund']
Responses
CodeDescriptionBody
201Createdobject
400Invalid bodystring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/playbooks \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "category": "customer_support",
  "description": "Verify the order, check eligibility, then issue the refund via the payment processor.",
  "display_name": "Refund Workflow",
  "name": "refund_workflow",
  "tags": [
    "refunds",
    "ecommerce"
  ],
  "tool_names": [
    "lookup_order",
    "verify_eligibility",
    "issue_refund"
  ]
}'

​
GET /api/v1/playbooks/{id}

Get a single playbook Looks up by uuid or snake_case name. Includes the markdown content from the prompts table. Parameters
NameInTypeRequiredDescription
idpathstringYesPlaybook id (uuid) or name
Responses
CodeDescriptionBody
200OKhandlers.Playbook
404Playbook not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
PUT /api/v1/playbooks/{id}

Update a playbook Default playbooks flip modified_from_default=TRUE on first update so re-seeds skip them. Parameters
NameInTypeRequiredDescription
idpathstringYesPlaybook id (uuid) or name
Request body (application/json) Schema: handlers.UpdatePlaybookRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
descriptionstringe.g. Updated copy after the Q2 process change.
display_namestringe.g. Refund Workflow (v2)
tagsarray<string>e.g. ['refunds', 'ecommerce', 'q2']
tool_namesarray<string>e.g. ['lookup_order', 'verify_eligibility', 'issue_refund_v2']
Responses
CodeDescriptionBody
200OKobject
404Playbook not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
  -X PUT \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "Updated copy after the Q2 process change.",
  "display_name": "Refund Workflow (v2)",
  "tags": [
    "refunds",
    "ecommerce",
    "q2"
  ],
  "tool_names": [
    "lookup_order",
    "verify_eligibility",
    "issue_refund_v2"
  ]
}'

​
DELETE /api/v1/playbooks/{id}

Delete a custom playbook Default (seeded) playbooks cannot be deleted — only custom ones. Parameters
NameInTypeRequiredDescription
idpathstringYesPlaybook id
Responses
CodeDescriptionBody
200OKobject
403Cannot delete default playbookstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"