Kataven Hub API — agents endpoints

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

Method	Path	Summary
`GET`	`/api/v1/agents`	List agents
`POST`	`/api/v1/agents`	Create 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}/faqs`	Attach an FAQ to an agent
`DELETE`	`/api/v1/agents/{id}/faqs/{faqId}`	Detach an FAQ from an agent
`POST`	`/api/v1/agents/{id}/playbooks`	Attach a playbook to an agent
`DELETE`	`/api/v1/agents/{id}/playbooks/{playbookId}`	Detach a playbook from an agent
`GET`	`/api/v1/agents/{id}/tools`	List tools attached to an agent
`POST`	`/api/v1/agents/{id}/tools`	Attach 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

Code	Description	Body
`200`	Array of agents.	`array<data.Agent>`
`400`	Missing X-Account-ID header — caller is using a JWT but didn’t supply the tenant header.	`string`
`401`	Missing or invalid Authorization bearer token.	`string`
`500`	Database 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.

Field	Type	Description
`auth_mode`	`string`	AuthMode gates whether the embeddable widget allows anonymous visitors. `public` accepts any visitor JWT; `authenticated` rejects guest tokens.
`background_audio_enabled`	`boolean`	e.g. `False`
`background_audio_volume`	`number`	e.g. `0.8`
`category`	`string`	e.g. `customer_support`
`description`	`string`	e.g. `Greets web visitors and answers product FAQs.`
`greeting_message`	`string`	e.g. `Hi, this is the ACME front desk — how can I help?`
`greeting_mode`	`string`	GreetingMode controls whether the agent’s opening line can be barged-in by the caller (interruptible) or must finish (locked).
`llm_model`	`string`	e.g. `gpt-4o`
`name`	`string`	e.g. `Front Desk`
`noise_suppression_enabled`	`boolean`	e.g. `True`
`ringing_enabled`	`boolean`	e.g. `True`
`status`	`string`	e.g. `active`
`system_prompt`	`string`	e.g. `You are a friendly front-desk assistant for ACME Corp.`
`template_id`	`string`	e.g. `tmpl_general_intake`
`voice_id`	`string`	e.g. `v1_friendly_female`
`voice_provider`	`string`	e.g. `cartesia`

Responses

Code	Description	Body
`201`	Agent persisted; the response carries the canonical row.	`data.Agent`
`400`	Invalid request body or missing required field.	`string`
`500`	Database 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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id

Responses

Code	Description	Body
`200`	OK	`data.Agent`
`404`	Not Found	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent 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.

Field	Type	Description
`auth_mode`	`string`	AuthMode gates whether the embeddable widget allows anonymous visitors. `public` accepts any visitor JWT; `authenticated` rejects guest tokens.
`background_audio_enabled`	`boolean`	e.g. `False`
`background_audio_volume`	`number`	e.g. `0.8`
`category`	`string`	e.g. `customer_support`
`description`	`string`	e.g. `Greets web visitors and answers product FAQs.`
`greeting_message`	`string`	e.g. `Hi, this is the ACME front desk — how can I help?`
`greeting_mode`	`string`	GreetingMode controls whether the agent’s opening line can be barged-in by the caller (interruptible) or must finish (locked).
`llm_model`	`string`	e.g. `gpt-4o`
`name`	`string`	e.g. `Front Desk`
`noise_suppression_enabled`	`boolean`	e.g. `True`
`ringing_enabled`	`boolean`	e.g. `True`
`status`	`string`	e.g. `active`
`system_prompt`	`string`	e.g. `You are a friendly front-desk assistant for ACME Corp.`
`template_id`	`string`	e.g. `tmpl_general_intake`
`voice_id`	`string`	e.g. `v1_friendly_female`
`voice_provider`	`string`	e.g. `cartesia`

Responses

Code	Description	Body
`200`	Updated	—
`400`	Invalid body	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id

Responses

Code	Description	Body
`204`	Deleted	—
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent 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.

Field	Type	Description
`faq_id`	`string`	e.g. `faq_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`

Responses

Code	Description	Body
`200`	OK	`object`
`400`	faq_id required	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id
`faqId`	path	`string`	Yes	FAQ id

Responses

Code	Description	Body
`200`	OK	`object`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent 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.

Field	Type	Description
`playbook_id`	`string`	e.g. `pb_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`

Responses

Code	Description	Body
`200`	OK	`object`
`400`	playbook_id required	`string`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id
`playbookId`	path	`string`	Yes	Playbook id

Responses

Code	Description	Body
`200`	OK	`object`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent id

Responses

Code	Description	Body
`200`	OK	`array<data.AgentTool>`
`500`	Database error	`string`

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

Name	In	Type	Required	Description
`id`	path	`string`	Yes	Agent 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.

Field	Type	Description
`agent_id`	`string`	e.g. `agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`
`config`	`object`
`enabled`	`boolean`	e.g. `True`
`tool_name`	`string`	e.g. `lookup_order`

Responses

Code	Description	Body
`200`	Saved	—
`400`	Invalid body	`string`
`500`	Database error	`string`

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"
}'

Get started

Resources

Kataven Hub API — agents endpoints

Endpoints at a glance

Reference

`GET /api/v1/agents`

`POST /api/v1/agents`

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

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

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

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

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

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

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

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

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

​Endpoints at a glance

​Reference

​GET /api/v1/agents

​POST /api/v1/agents

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

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

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

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

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

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

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

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

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

Endpoints at a glance

Reference

`GET /api/v1/agents`

`POST /api/v1/agents`

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

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

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

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

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

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

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

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

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