Python SDK

Official Python client for the Kataven Hub API.

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

pip install kataven

Quickstart

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="[phone]", provider="twilio", credentials_id=provider["id"])
result = client.calls.originate(from_number="[phone]", to_number="[phone]", 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 ⚠️ secret returned ONCE on create
client.widget_settings	get, update, get_agent, update_agent

Intentionally not in the SDK (admin / dashboard-only operations): client.config, client.settings, client.spokes, client.users, client.accounts, 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/hub-api
timeout	30 seconds