> ## 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 Reference — voice AI REST API

> Complete REST API reference for the Kataven Hub voice AI platform — agents, tools, telephony, calls, campaigns, widget management. Generated from OpenAPI 3.1, with try-it on every endpoint.

The Kataven Hub REST API is the canonical management surface for your account. Every dashboard screen at [hub.kataven.ai](https://hub.kataven.ai), the [Python SDK](/sdks/python/overview), the [Node SDK](/sdks/node/overview), and the [MCP server](/sdks/mcp/overview) all sit on top of this same API — they're convenience wrappers, not separate products.

Use REST directly when:

* You're writing in a language we don't ship an SDK for (Go, Rust, Ruby, PHP, Java, Elixir, Bash, ...).
* You're hitting Kataven from a CI pipeline or webhook handler where adding a runtime dependency is overkill.
* You're debugging an SDK call and want to see the raw HTTP request and response.

Otherwise — pick the SDK or MCP that fits your runtime; same endpoints, less boilerplate.

## Resources

Every endpoint is grouped under a resource in the sidebar. Each resource page lists every endpoint, with parameters, response codes, schema fields, and copy-paste examples in **curl, Python, and Node**.

| Resource                                       | What's there                                      |
| ---------------------------------------------- | ------------------------------------------------- |
| [Agents](/api-reference/agents)                | CRUD + tool / playbook / FAQ associations         |
| [Tools](/api-reference/tools)                  | Built-in catalog + custom tools                   |
| [Playbooks](/api-reference/playbooks)          | Reusable knowledge bundles                        |
| [FAQs](/api-reference/faqs)                    | Quick-lookup question/answer entries              |
| [Marketplace](/api-reference/marketplace)      | Browse + install pre-built templates              |
| [Integrations](/api-reference/integrations)    | Stripe, Shopify, Slack with encrypted credentials |
| [Telephony](/api-reference/telephony)          | Twilio / Plivo / Vobiz creds + phone numbers      |
| [Calls](/api-reference/calls)                  | Outbound call origination                         |
| [Recordings](/api-reference/recordings)        | Presigned-URL playback                            |
| [Call Limits](/api-reference/call-limits)      | Per-tenant cost caps (read-only via API)          |
| [Campaigns](/api-reference/campaigns)          | Bulk-dial outbound from CSV                       |
| [API Keys](/api-reference/api-keys)            | sk\_live\_ credentials                            |
| [Widget Keys](/api-reference/widget-keys)      | pk\_live\_ public widget identifiers              |
| [Widget Settings](/api-reference/widget-admin) | Widget branding + per-agent policy                |
| [Widget Auth](/api-reference/widget-auth)      | Public widget visitor auth (cross-origin)         |

## Conventions

* **Base URL.** `https://api.kataven.ai/v1`. Production. Outages on `hub.kataven.ai` (the dashboard) don't affect this; rate-limit and monitoring policies apply independently.
* **Authentication.** `Authorization: Bearer <token>`. Token is either an `sk_live_…` API key (preferred — see [Authentication](/authentication)) or a Zitadel JWT (interactive admin sessions only). `sk_live_` callers don't need an `X-Account-ID` header — the account is in the prefix.
* **Content type.** `application/json` for request and response bodies. Multipart used by `POST /v1/campaigns` (CSV upload).
* **Idempotency.** Read endpoints (`GET`) are safe to retry. Write endpoints (`POST`/`PATCH`/`DELETE`) are not idempotent today — don't blindly retry on connection errors. Idempotency-Key support is on the roadmap.

## Status codes you'll see across the surface

| Code                  | Meaning                                                                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `200` / `201` / `204` | Success.                                                                                                                                         |
| `400`                 | Bad request — usually a missing required field, malformed JSON, or invalid path parameter.                                                       |
| `401`                 | Bearer token missing or invalid.                                                                                                                 |
| `403`                 | Endpoint requires Hub UI auth (e.g. API key CRUD, cost caps), or the reserved `kataven-admin` account is rejected.                               |
| `404`                 | Resource not found in this account.                                                                                                              |
| `409`                 | State conflict (e.g. delete a non-draft campaign, delete a provider with attached numbers).                                                      |
| `429`                 | Cost cap exceeded (concurrent / per-minute / daily). View limits at [hub.kataven.ai/settings](https://hub.kataven.ai/settings) → **Limits** tab. |
| `5xx`                 | Server error. Retry once with exponential backoff; if it persists, [email support](mailto:support@kataven.ai).                                   |