> ## 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.

# Python SDK — playbooks

> Python SDK reference for Kataven playbooks — reusable knowledge bundles attached to one or more agents.

`PlaybooksClient` is reachable on every Kataven client as `client.playbooks`. Each method maps to one HTTP endpoint on the [Hub API](/api-reference/introduction); links to the underlying spec entry are inline below.

Playbooks are reusable knowledge bundles (system-prompt fragments + tool lists) you attach to agents. CRUD via `client.playbooks`; attach/detach via `client.agents.attach_playbook`.

## Methods at a glance

| Method   | HTTP                                          | Summary                  |
| -------- | --------------------------------------------- | ------------------------ |
| `list`   | `GET /api/playbooks`                          | List playbooks           |
| `get`    | `GET /api/playbooks/{playbook_id_or_name}`    | Get a single playbook    |
| `create` | `POST /api/playbooks`                         | Create a custom playbook |
| `update` | `PUT /api/playbooks/{playbook_id_or_name}`    | Update a playbook        |
| `delete` | `DELETE /api/playbooks/{playbook_id_or_name}` | Delete a custom playbook |

## Reference

### `client.playbooks.list(...)`

List playbooks

**HTTP** — `GET /api/playbooks` · [API reference →](/api-reference/introduction#tag/Playbooks/operation/getApiPlaybooks)

```python theme={null}
    def list(
        self,
        category: Optional[str] = None,
        search: Optional[str] = None,
        limit: int = 10,
        offset: int = 0,
    ) -> Dict[str, Any]:
```

### `client.playbooks.get(...)`

Get a single playbook

**HTTP** — `GET /api/playbooks/{id}` · [API reference →](/api-reference/introduction#tag/Playbooks/operation/getApiPlaybooksById)

```python theme={null}
    def get(self, playbook_id_or_name: str) -> Dict[str, Any]:
```

Looks up by uuid or snake\_case name. Includes the markdown content from the prompts table.

### `client.playbooks.create(...)`

Create a custom playbook

**HTTP** — `POST /api/playbooks` · [API reference →](/api-reference/introduction#tag/Playbooks/operation/postApiPlaybooks)

```python theme={null}
    def create(
        self,
        display_name: str,
        name: Optional[str] = None,
        category: str = "custom",
        description: str = "",
        tool_names: Optional[List[str]] = None,
        tags: Optional[List[str]] = None,
    ) -> Dict[str, Any]:
```

### `client.playbooks.update(...)`

Update a playbook

**HTTP** — `PUT /api/playbooks/{id}` · [API reference →](/api-reference/introduction#tag/Playbooks/operation/putApiPlaybooksById)

```python theme={null}
    def update(self, playbook_id_or_name: str, **kwargs) -> Dict[str, Any]:
```

Default playbooks flip modified\_from\_default=TRUE on first update so re-seeds skip them.

### `client.playbooks.delete(...)`

Delete a custom playbook

**HTTP** — `DELETE /api/playbooks/{id}` · [API reference →](/api-reference/introduction#tag/Playbooks/operation/deleteApiPlaybooksById)

```python theme={null}
    def delete(self, playbook_id_or_name: str) -> Dict[str, Any]:
```

Default (seeded) playbooks cannot be deleted — only custom ones.