Skip to main content
Agents are the configurable units that handle conversations — system prompt, voice, LLM, attached tools/playbooks/FAQs. Same operations are wrapped by the Python SDK and the Node SDK.

​
Endpoints at a glance

MethodPathSummary
GET/api/v1/agentsList agents
POST/api/v1/agentsCreate an agent
GET/api/v1/agents/{id}Get an agent
PATCH/api/v1/agents/{id}Update an agent
DELETE/api/v1/agents/{id}Delete an agent
POST/api/v1/agents/{id}/faqsAttach an FAQ to an agent
DELETE/api/v1/agents/{id}/faqs/{faqId}Detach an FAQ from an agent
POST/api/v1/agents/{id}/playbooksAttach a playbook to an agent
DELETE/api/v1/agents/{id}/playbooks/{playbookId}Detach a playbook from an agent
GET/api/v1/agents/{id}/toolsList tools attached to an agent
POST/api/v1/agents/{id}/toolsAttach or update a tool on an agent

​
Reference

​
GET /api/v1/agents

List agents Returns every agent in the caller’s account, with attached playbooks and FAQs joined in. Ordered by created_at descending. There is no pagination today — every account has at most a few dozen agents in practice; if that changes we’ll add limit/offset like /api/tools and /api/playbooks. Responses
CodeDescriptionBody
200Array of agents.array<data.Agent>
400Missing X-Account-ID header — caller is using a JWT but didn’t supply the tenant header.string
401Missing or invalid Authorization bearer token.string
500Database error.string
Example 
curl https://api.kataven.ai/v1/agents \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/agents

Create an agent Persists a new agent in the caller’s account. Required body fields: name. Most other fields default sensibly: category=custom, status=draft, llm_model=gpt-4o, voice_provider=cartesia, auth_mode=authenticated, greeting_mode=interruptible. Returns the inserted row, including server-set id, created_at, and updated_at. Attach playbooks and FAQs separately via POST /api/agents/{id}/playbooks and POST /api/agents/{id}/faqs. Request body (application/json) Schema: data.Agent. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
auth_modestringAuthMode gates whether the embeddable widget allows anonymous visitors. public accepts any visitor JWT; authenticated rejects guest tokens.
background_audio_enabledbooleane.g. False
background_audio_volumenumbere.g. 0.8
categorystringe.g. customer_support
descriptionstringe.g. Greets web visitors and answers product FAQs.
greeting_messagestringe.g. Hi, this is the ACME front desk — how can I help?
greeting_modestringGreetingMode controls whether the agent’s opening line can be barged-in by the caller (interruptible) or must finish (locked).
llm_modelstringe.g. gpt-4o
namestringe.g. Front Desk
noise_suppression_enabledbooleane.g. True
ringing_enabledbooleane.g. True
statusstringe.g. active
system_promptstringe.g. You are a friendly front-desk assistant for ACME Corp.
template_idstringe.g. tmpl_general_intake
voice_idstringe.g. v1_friendly_female
voice_providerstringe.g. cartesia
Responses
CodeDescriptionBody
201Agent persisted; the response carries the canonical row.data.Agent
400Invalid request body or missing required field.string
500Database error.string
Example 
curl https://api.kataven.ai/v1/agents \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "auth_mode": "authenticated",
  "background_audio_enabled": false,
  "background_audio_volume": 0.8,
  "category": "customer_support",
  "description": "Greets web visitors and answers product FAQs.",
  "greeting_message": "Hi, this is the ACME front desk — how can I help?",
  "greeting_mode": "interruptible",
  "llm_model": "gpt-4o",
  "name": "Front Desk",
  "noise_suppression_enabled": true,
  "ringing_enabled": true,
  "status": "active",
  "system_prompt": "You are a friendly front-desk assistant for ACME Corp.",
  "template_id": "tmpl_general_intake",
  "voice_id": "v1_friendly_female",
  "voice_provider": "cartesia"
}'

​
GET /api/v1/agents/{id}

Get an agent Returns the agent row plus its attached playbooks and FAQs. Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Responses
CodeDescriptionBody
200OKdata.Agent
404Not Foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
PATCH /api/v1/agents/{id}

Update an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Request body (application/json) Schema: data.Agent. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
auth_modestringAuthMode gates whether the embeddable widget allows anonymous visitors. public accepts any visitor JWT; authenticated rejects guest tokens.
background_audio_enabledbooleane.g. False
background_audio_volumenumbere.g. 0.8
categorystringe.g. customer_support
descriptionstringe.g. Greets web visitors and answers product FAQs.
greeting_messagestringe.g. Hi, this is the ACME front desk — how can I help?
greeting_modestringGreetingMode controls whether the agent’s opening line can be barged-in by the caller (interruptible) or must finish (locked).
llm_modelstringe.g. gpt-4o
namestringe.g. Front Desk
noise_suppression_enabledbooleane.g. True
ringing_enabledbooleane.g. True
statusstringe.g. active
system_promptstringe.g. You are a friendly front-desk assistant for ACME Corp.
template_idstringe.g. tmpl_general_intake
voice_idstringe.g. v1_friendly_female
voice_providerstringe.g. cartesia
Responses
CodeDescriptionBody
200Updated—
400Invalid bodystring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N... \
  -X PATCH \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "auth_mode": "authenticated",
  "background_audio_enabled": false,
  "background_audio_volume": 0.8,
  "category": "customer_support",
  "description": "Greets web visitors and answers product FAQs.",
  "greeting_message": "Hi, this is the ACME front desk — how can I help?",
  "greeting_mode": "interruptible",
  "llm_model": "gpt-4o",
  "name": "Front Desk",
  "noise_suppression_enabled": true,
  "ringing_enabled": true,
  "status": "active",
  "system_prompt": "You are a friendly front-desk assistant for ACME Corp.",
  "template_id": "tmpl_general_intake",
  "voice_id": "v1_friendly_female",
  "voice_provider": "cartesia"
}'

​
DELETE /api/v1/agents/{id}

Delete an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Responses
CodeDescriptionBody
204Deleted—
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/agents/{id}/faqs

Attach an FAQ to an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Request body (application/json) Schema: handlers.AttachFAQRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
faq_idstringe.g. faq_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
Responses
CodeDescriptionBody
200OKobject
400faq_id requiredstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../faqs \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "faq_id": "faq_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z"
}'

​
DELETE /api/v1/agents/{id}/faqs/{faqId}

Detach an FAQ from an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
faqIdpathstringYesFAQ id
Responses
CodeDescriptionBody
200OKobject
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../faqs/faq_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/agents/{id}/playbooks

Attach a playbook to an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Request body (application/json) Schema: handlers.AttachPlaybookRequest. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
playbook_idstringe.g. pb_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
Responses
CodeDescriptionBody
200OKobject
400playbook_id requiredstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../playbooks \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "playbook_id": "pb_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z"
}'

​
DELETE /api/v1/agents/{id}/playbooks/{playbookId}

Detach a playbook from an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
playbookIdpathstringYesPlaybook id
Responses
CodeDescriptionBody
200OKobject
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../playbooks/playbook_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
GET /api/v1/agents/{id}/tools

List tools attached to an agent Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Responses
CodeDescriptionBody
200OKarray<data.AgentTool>
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../tools \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
POST /api/v1/agents/{id}/tools

Attach or update a tool on an agent Idempotent insert-or-update of one (agent_id, tool_name) row. Both POST and PUT are accepted. Parameters
NameInTypeRequiredDescription
idpathstringYesAgent id
Request body (application/json) Schema: data.AgentTool. Server-set fields (id, created_at, updated_at, …) are ignored if supplied; only the user-settable fields are shown below.
FieldTypeDescription
agent_idstringe.g. agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z
configobject
enabledbooleane.g. True
tool_namestringe.g. lookup_order
Responses
CodeDescriptionBody
200Saved—
400Invalid bodystring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../tools \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
  "enabled": true,
  "tool_name": "lookup_order"
}'