> ## 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 — outbound calls

> REST API reference for placing outbound voice calls programmatically.

Place outbound voice calls. Server enforces caller-ID ownership and per-tenant cost caps. Wrapped by the [Python SDK](/sdks/python/calls) and [Node SDK](/sdks/node/calls).

## Endpoints at a glance

| Method | Path                                                      | Summary                    |
| ------ | --------------------------------------------------------- | -------------------------- |
| `POST` | [`/api/v1/calls/originate`](#post-api-v1-calls-originate) | Originate an outbound call |

## Reference

### `POST /api/v1/calls/originate`

Originate an outbound call

Places an outbound call from one of your registered phone numbers to an arbitrary E.164 destination using a configured agent. Subject to per-tenant cost caps (see /api/v1/call-limits).

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

Schema: `handlers.originateRequest`. 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` |
| `from_number` | `string` | e.g. `+12025550123`                     |
| `to_number`   | `string` | e.g. `+14155550100`                     |

**Responses**

| Code  | Description                     | Body     |
| ----- | ------------------------------- | -------- |
| `200` | OK                              | `object` |
| `400` | Invalid body or missing field   | `string` |
| `404` | Phone number or agent not found | `string` |
| `429` | Cost cap exceeded               | `string` |
| `500` | Carrier or database error       | `string` |

**Example**

<CodeGroup>
  ```bash curl theme={null}
  curl https://api.kataven.ai/v1/calls/originate \
    -X POST \
    -H "Authorization: Bearer $KATAVEN_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "agent_id": "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    "from_number": "+12025550123",
    "to_number": "+14155550100"
  }'
  ```

  ```python Python SDK theme={null}
  from kataven import KatavenClient

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.calls.originate(
      agent_id="agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
      from_number="+12025550123",
      to_number="+14155550100",
  )
  ```

  ```typescript Node SDK theme={null}
  import { Kataven } from "@kataven/server";

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.calls.originate({
    agent_id: "agent_01HZ2N7G3K8M0Q5R7T9V2X4Y6Z",
    from_number: "+12025550123",
    to_number: "+14155550100",
  });
  ```
</CodeGroup>