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

> Official Python client for the Kataven Hub API.

The `kataven` Python package wraps every Hub API endpoint with a
typed, ergonomic client.

```bash theme={null}
pip install kataven
```

## Quickstart

```python theme={null}
from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY + KATAVEN_ACCOUNT_ID

# CRUD
agents = client.agents.list()
agent = client.agents.create(name="Front Desk", system_prompt="...")
client.agents.update(agent["id"], status="active")
client.agents.delete(agent["id"])

# Tools, knowledge
tools = client.tools.list(category="calendar", limit=20)
faq = client.faqs.create(name="hours", category="general", title="Hours?", content="9–6 PT")
client.agents.attach_faq(agent["id"], faq["id"])

# Telephony
provider = client.telephony.create_provider(provider="twilio", label="Prod", credentials={...})
number = client.telephony.create_number(e164="+12025550123", provider="twilio", credentials_id=provider["id"])
result = client.calls.originate(from_number="+12025550123", to_number="+14155550100", agent_id=agent["id"])

# Campaigns (CSV upload)
with open("contacts.csv", "rb") as f:
    campaign = client.campaigns.create(
        name="Outreach", agent_id=agent["id"],
        phone_number_id=number["id"], contacts=f, max_concurrent_calls=5,
    )
client.campaigns.start(campaign["id"])

# Live SSE metrics
for event in client.campaigns.stream_events(campaign["id"]):
    print(event)
```

## Resources

| Resource                 | Methods                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `client.agents`          | `list`, `get`, `create`, `update`, `delete`, `list_tools`, `upsert_tool`, `attach_playbook`, `detach_playbook`, `attach_faq`, `detach_faq` |
| `client.tools`           | `list`, `get`, `create`, `update`, `delete`                                                                                                |
| `client.playbooks`       | `list`, `get`, `create`, `update`, `delete`                                                                                                |
| `client.faqs`            | `list`, `get`, `create`, `update`, `delete`                                                                                                |
| `client.marketplace`     | `list`, `get`, `install`, `categories`                                                                                                     |
| `client.integrations`    | `list`, `get`, `install`, `uninstall`                                                                                                      |
| `client.telephony`       | `list_providers`, `create_provider`, `delete_provider`, `list_numbers`, `create_number`, `update_number`, `delete_number`                  |
| `client.calls`           | `originate`                                                                                                                                |
| `client.recordings`      | `get`                                                                                                                                      |
| `client.call_limits`     | `get` *(read-only — caps are platform-team controlled)*                                                                                    |
| `client.campaigns`       | `list`, `get`, `create`, `start`, `pause`, `resume`, `stop`, `delete`, `list_contacts`, `stream_events`                                    |
| `client.widget_keys`     | `list`, `create`, `update`, `delete` — `pk_live_` for HTML embeds; `public_key` returned ONCE on create                                    |
| `client.widget_settings` | `get`, `update`, `get_agent`, `update_agent`                                                                                               |

**API key (sk\_live\_) management is deliberately not exposed in the SDK.**
A leaked `sk_live_` shouldn't be able to mint another `sk_live_` —
otherwise rotation isn't a real defense. Server enforces this with
`403 Forbidden` on `POST/PATCH/DELETE /api/v1/api-keys` for
`sk_live_` callers; the SDK doesn't bother trying. Manage keys at
**Hub UI → Settings → API Keys** (Zitadel JWT auth required).

**Intentionally not in the SDK** (admin / dashboard-only operations):
`client.config`, `client.settings`, `client.spokes`, `client.users`,
`client.accounts`, `client.api_keys`, `recordings.delete`,
`call_limits.update`, `marketplace.create_template`,
`integrations.create`.

## Errors

The SDK raises subclasses of `KatavenError`:

| Exception             | When                    |
| --------------------- | ----------------------- |
| `AuthenticationError` | 401                     |
| `PermissionError`     | 403                     |
| `NotFoundError`       | 404                     |
| `ConflictError`       | 409                     |
| `RateLimitError`      | 429 (cost-cap exceeded) |
| `ServerError`         | 5xx                     |

Generic `KatavenError` carries the response body and status for
anything else.

## Configuration

| Param / env                         | Default                     |
| ----------------------------------- | --------------------------- |
| `api_key` / `KATAVEN_API_KEY`       | required                    |
| `account_id` / `KATAVEN_ACCOUNT_ID` | required                    |
| `base_url` / `KATAVEN_BASE_URL`     | `https://api.kataven.ai/v1` |
| `timeout`                           | 30 seconds                  |