Kataven Hub API — playbooks endpoints

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

Endpoints at a glance

Method	Path	Summary
`GET`	`/api/v1/playbooks`	List playbooks
`POST`	`/api/v1/playbooks`	Create 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

Name	In	Type	Required	Description
`category`	query	`string`	No	Filter by category
`search`	query	`string`	No	Prefix search on name
`limit`	query	`integer`	No	Page size (1-100, default 10)
`offset`	query	`integer`	No	Pagination offset (default 0)

Responses

Code	Description	Body
`200`	OK	`object`
`400`	Missing X-Account-ID header	`string`
`500`	Database error	`string`

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.

Field	Type	Description
`category`	`string`	e.g. `customer_support`
`description`	`string`	e.g. `Verify the order, check eligibility, then issue the refund via the payment processor.`
`display_name`	`string`	e.g. `Refund Workflow`
`name`	`string`	e.g. `refund_workflow`
`tags`	`array<string>`	e.g. `['refunds', 'ecommerce']`
`tool_names`	`array<string>`	e.g. `['lookup_order', 'verify_eligibility', 'issue_refund']`

Responses

Code	Description	Body
`201`	Created	`object`
`400`	Invalid body	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Playbook id (uuid) or name

Responses

Code	Description	Body
`200`	OK	`handlers.Playbook`
`404`	Playbook not found	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Playbook 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.

Field	Type	Description
`description`	`string`	e.g. `Updated copy after the Q2 process change.`
`display_name`	`string`	e.g. `Refund Workflow (v2)`
`tags`	`array<string>`	e.g. `['refunds', 'ecommerce', 'q2']`
`tool_names`	`array<string>`	e.g. `['lookup_order', 'verify_eligibility', 'issue_refund_v2']`

Responses

Code	Description	Body
`200`	OK	`object`
`404`	Playbook not found	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Playbook id

Responses

Code	Description	Body
`200`	OK	`object`
`403`	Cannot delete default playbook	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

Get started

Resources

Kataven Hub API — playbooks endpoints

Endpoints at a glance

Reference

`GET /api/v1/playbooks`

`POST /api/v1/playbooks`

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

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

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

​Endpoints at a glance

​Reference

​GET /api/v1/playbooks

​POST /api/v1/playbooks

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

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

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

Endpoints at a glance

Reference

`GET /api/v1/playbooks`

`POST /api/v1/playbooks`

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

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

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