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

> REST API reference for Kataven telephony — Twilio/Plivo/Vobiz credentials and phone-number management.

Carrier credentials and phone-number management. Wrapped by the [Python SDK](/sdks/python/telephony) and [Node SDK](/sdks/node/telephony).

## Endpoints at a glance

| Method   | Path                                                                        | Summary                                 |
| -------- | --------------------------------------------------------------------------- | --------------------------------------- |
| `GET`    | [`/api/v1/telephony/numbers`](#get-api-v1-telephony-numbers)                | List phone numbers                      |
| `POST`   | [`/api/v1/telephony/numbers`](#post-api-v1-telephony-numbers)               | Register a phone number                 |
| `PATCH`  | [`/api/v1/telephony/numbers/{id}`](#patch-api-v1-telephony-numbers-id)      | Pin or unpin a phone number to an agent |
| `DELETE` | [`/api/v1/telephony/numbers/{id}`](#delete-api-v1-telephony-numbers-id)     | Delete a phone number                   |
| `GET`    | [`/api/v1/telephony/providers`](#get-api-v1-telephony-providers)            | List telephony provider credentials     |
| `POST`   | [`/api/v1/telephony/providers`](#post-api-v1-telephony-providers)           | Add a telephony provider credential     |
| `DELETE` | [`/api/v1/telephony/providers/{id}`](#delete-api-v1-telephony-providers-id) | Delete a telephony provider credential  |

## Reference

### `GET /api/v1/telephony/numbers`

List phone numbers

**Parameters**

| Name       | In    | Type     | Required | Description        |
| ---------- | ----- | -------- | -------- | ------------------ |
| `agent_id` | query | `string` | No       | Filter by agent id |

**Responses**

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

**Example**

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

### `POST /api/v1/telephony/numbers`

Register a phone number

Binds an E.164 number to a carrier credential row and (optionally) pins it to one agent. Inbound + outbound default to enabled.

**Request body** (`application/json`)

Schema: `handlers.CreateNumberRequest`. 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` |
| `credentials_id`   | `string`  | e.g. `prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z`  |
| `e164`             | `string`  | e.g. `+12025550123`                     |
| `inbound_enabled`  | `boolean` | e.g. `True`                             |
| `outbound_enabled` | `boolean` | e.g. `True`                             |
| `provider`         | `string`  | e.g. `twilio`                           |

**Responses**

| Code  | Description                      | Body     |
| ----- | -------------------------------- | -------- |
| `201` | Created                          | `object` |
| `400` | Invalid body or duplicate number | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/telephony/numbers \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    "credentials_id": "prov_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    "e164": "+12025550123",
    "inbound_enabled": true,
    "outbound_enabled": true,
    "provider": "twilio"
  }'
  ```
</CodeGroup>

### `PATCH /api/v1/telephony/numbers/{id}`

Pin or unpin a phone number to an agent

**Parameters**

| Name | In   | Type     | Required | Description            |
| ---- | ---- | -------- | -------- | ---------------------- |
| `id` | path | `string` | Yes      | Phone number id (uuid) |

**Request body** (`application/json`)

Schema: `handlers.UpdateNumberRequest`. 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` |

**Responses**

| Code  | Description            | Body     |
| ----- | ---------------------- | -------- |
| `204` | Updated                | —        |
| `404` | Phone number not found | `string` |
| `500` | Database error         | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/telephony/numbers/agent_01HZ2N... \
    -X PATCH \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z"
  }'
  ```
</CodeGroup>

### `DELETE /api/v1/telephony/numbers/{id}`

Delete a phone number

**Parameters**

| Name | In   | Type     | Required | Description            |
| ---- | ---- | -------- | -------- | ---------------------- |
| `id` | path | `string` | Yes      | Phone number id (uuid) |

**Responses**

| Code  | Description            | Body     |
| ----- | ---------------------- | -------- |
| `204` | Deleted                | —        |
| `404` | Phone number not found | `string` |
| `500` | Database error         | `string` |

**Example**

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

### `GET /api/v1/telephony/providers`

List telephony provider credentials

Returns metadata about every carrier credential configured for this account. Plaintext credentials are not returned.

**Responses**

| Code  | Description                 | Body     |
| ----- | --------------------------- | -------- |
| `200` | OK                          | `object` |
| `400` | Missing X-Account-ID header | `string` |
| `500` | Database error              | `string` |

**Example**

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

### `POST /api/v1/telephony/providers`

Add a telephony provider credential

Encrypts the credentials JSON via the Secret Encryptor service, then inserts the row. Plaintext is never persisted.

**Request body** (`application/json`)

Schema: `handlers.CreateProviderRequest`. Server-set fields (`id`, `created_at`, `updated_at`, …) are ignored if supplied; only the user-settable fields are shown below.

| Field         | Type     | Description              |
| ------------- | -------- | ------------------------ |
| `credentials` | `object` |                          |
| `label`       | `string` | e.g. `Production Twilio` |
| `provider`    | `string` | e.g. `twilio`            |

**Responses**

| Code  | Description                    | Body     |
| ----- | ------------------------------ | -------- |
| `201` | Created                        | `object` |
| `400` | Invalid body or missing field  | `string` |
| `500` | Database error                 | `string` |
| `503` | Encryption service unavailable | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/telephony/providers \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "label": "Production Twilio",
    "provider": "twilio"
  }'
  ```
</CodeGroup>

### `DELETE /api/v1/telephony/providers/{id}`

Delete a telephony provider credential

Refuses if any phone-number row still references this credential — detach numbers first.

**Parameters**

| Name | In   | Type     | Required | Description          |
| ---- | ---- | -------- | -------- | -------------------- |
| `id` | path | `string` | Yes      | Credential id (uuid) |

**Responses**

| Code  | Description                        | Body     |
| ----- | ---------------------------------- | -------- |
| `204` | Deleted                            | —        |
| `404` | Credential not found               | `string` |
| `409` | Credential in use by phone numbers | `string` |
| `500` | Database error                     | `string` |

**Example**

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