Skip to main content
The Kataven Hub REST API is the canonical management surface for your account. Every dashboard screen at hub.kataven.ai, the Python SDK, the Node SDK, and the MCP server 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.
ResourceWhat’s there
AgentsCRUD + tool / playbook / FAQ associations
ToolsBuilt-in catalog + custom tools
PlaybooksReusable knowledge bundles
FAQsQuick-lookup question/answer entries
MarketplaceBrowse + install pre-built templates
IntegrationsStripe, Shopify, Slack with encrypted credentials
TelephonyTwilio / Plivo / Vobiz creds + phone numbers
CallsOutbound call origination
RecordingsPresigned-URL playback
Call LimitsPer-tenant cost caps (read-only via API)
CampaignsBulk-dial outbound from CSV
API Keyssk_live_ credentials
Widget Keyspk_live_ public widget identifiers
Widget SettingsWidget branding + per-agent policy
Widget AuthPublic 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) 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

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