> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kataven.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Kataven Hub API — playbooks endpoints

> REST API reference for Kataven playbooks — reusable knowledge bundles attached to agents.

Playbooks are reusable knowledge bundles you attach to agents. Wrapped by the [Python SDK](/sdks/python/playbooks) and [Node SDK](/sdks/node/playbooks).

## Endpoints at a glance

| Method   | Path                                                    | Summary                  |
| -------- | ------------------------------------------------------- | ------------------------ |
| `GET`    | [`/api/v1/playbooks`](#get-api-v1-playbooks)            | List playbooks           |
| `POST`   | [`/api/v1/playbooks`](#post-api-v1-playbooks)           | Create a custom playbook |
| `GET`    | [`/api/v1/playbooks/{id}`](#get-api-v1-playbooks-id)    | Get a single playbook    |
| `PUT`    | [`/api/v1/playbooks/{id}`](#put-api-v1-playbooks-id)    | Update a playbook        |
| `DELETE` | [`/api/v1/playbooks/{id}`](#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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/playbooks \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
    ]
  }'
  ```
</CodeGroup>

### `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`](#schemas) |
| `404` | Playbook not found | `string`                        |
| `500` | Database error     | `string`                        |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
    ]
  }'
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/playbooks/agent_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>