> ## 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 — agents endpoints

> REST API reference for Kataven agents — list, get, create, update, delete, plus tool/playbook/FAQ associations.

Agents are the configurable units that handle conversations — system prompt, voice, LLM, attached tools/playbooks/FAQs. Same operations are wrapped by the [Python SDK](/sdks/python/agents) and the [Node SDK](/sdks/node/agents).

## Endpoints at a glance

| Method   | Path                                                                                          | Summary                             |
| -------- | --------------------------------------------------------------------------------------------- | ----------------------------------- |
| `GET`    | [`/api/v1/agents`](#get-api-v1-agents)                                                        | List agents                         |
| `POST`   | [`/api/v1/agents`](#post-api-v1-agents)                                                       | Create an agent                     |
| `GET`    | [`/api/v1/agents/{id}`](#get-api-v1-agents-id)                                                | Get an agent                        |
| `PATCH`  | [`/api/v1/agents/{id}`](#patch-api-v1-agents-id)                                              | Update an agent                     |
| `DELETE` | [`/api/v1/agents/{id}`](#delete-api-v1-agents-id)                                             | Delete an agent                     |
| `POST`   | [`/api/v1/agents/{id}/faqs`](#post-api-v1-agents-id-faqs)                                     | Attach an FAQ to an agent           |
| `DELETE` | [`/api/v1/agents/{id}/faqs/{faqId}`](#delete-api-v1-agents-id-faqs-faqid)                     | Detach an FAQ from an agent         |
| `POST`   | [`/api/v1/agents/{id}/playbooks`](#post-api-v1-agents-id-playbooks)                           | Attach a playbook to an agent       |
| `DELETE` | [`/api/v1/agents/{id}/playbooks/{playbookId}`](#delete-api-v1-agents-id-playbooks-playbookid) | Detach a playbook from an agent     |
| `GET`    | [`/api/v1/agents/{id}/tools`](#get-api-v1-agents-id-tools)                                    | List tools attached to an agent     |
| `POST`   | [`/api/v1/agents/{id}/tools`](#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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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`](#schemas) |
| `400` | Invalid request body or missing required field.          | `string`                 |
| `500` | Database error.                                          | `string`                 |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  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"
  }'
  ```
</CodeGroup>

### `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`](#schemas) |
| `404` | Not Found      | `string`                 |
| `500` | Database error | `string`                 |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N... \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
  }'
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
  }'
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../faqs/faq_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
  }'
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../playbooks/playbook_01HZ2N... \
    -X DELETE \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/agents/agent_01HZ2N.../tools \
    -H "Authorization: Bearer $KATAVEN_API_KEY"
  ```
</CodeGroup>

### `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**

<CodeGroup>
  ```bash curl theme={null}
  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"
  }'
  ```
</CodeGroup>