> ## 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 campaigns

> REST API reference for Kataven outbound campaigns — bulk-dial from CSV with cap-aware concurrency and live SSE metrics.

Bulk outbound campaigns dialled from CSV with cap-aware concurrency and live SSE metrics. Wrapped by the [Python SDK](/sdks/python/campaigns) and [Node SDK](/sdks/node/campaigns).

## Endpoints at a glance

| Method   | Path                                                                   | Summary                     |
| -------- | ---------------------------------------------------------------------- | --------------------------- |
| `GET`    | [`/api/v1/campaigns`](#get-api-v1-campaigns)                           | List campaigns              |
| `POST`   | [`/api/v1/campaigns`](#post-api-v1-campaigns)                          | Create a campaign           |
| `GET`    | [`/api/v1/campaigns/{id}`](#get-api-v1-campaigns-id)                   | Get a campaign              |
| `DELETE` | [`/api/v1/campaigns/{id}`](#delete-api-v1-campaigns-id)                | Delete a campaign           |
| `GET`    | [`/api/v1/campaigns/{id}/contacts`](#get-api-v1-campaigns-id-contacts) | List contacts in a campaign |
| `GET`    | [`/api/v1/campaigns/{id}/events`](#get-api-v1-campaigns-id-events)     | Stream campaign events      |
| `POST`   | [`/api/v1/campaigns/{id}/pause`](#post-api-v1-campaigns-id-pause)      | Pause a running campaign    |
| `POST`   | [`/api/v1/campaigns/{id}/resume`](#post-api-v1-campaigns-id-resume)    | Resume a paused campaign    |
| `POST`   | [`/api/v1/campaigns/{id}/start`](#post-api-v1-campaigns-id-start)      | Start a campaign            |
| `POST`   | [`/api/v1/campaigns/{id}/stop`](#post-api-v1-campaigns-id-stop)        | Stop a campaign permanently |

## Reference

### `GET /api/v1/campaigns`

List campaigns

**Responses**

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

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.list()
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.list();
  ```
</CodeGroup>

### `POST /api/v1/campaigns`

Create a campaign

Multipart form upload — `contacts` is a CSV file, every other field is a form value. The CSV must contain at least a `phone_number` column. The campaign is created in `draft` state and dispatch starts only after `start`.

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

**Responses**

| Code  | Description        | Body                        |
| ----- | ------------------ | --------------------------- |
| `201` | Created            | [`data.Campaign`](#schemas) |
| `400` | Invalid form / CSV | `string`                    |
| `500` | Database error     | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.create(# body fields go here)
  ```
</CodeGroup>

### `GET /api/v1/campaigns/{id}`

Get a campaign

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description        | Body                        |
| ----- | ------------------ | --------------------------- |
| `200` | OK                 | [`data.Campaign`](#schemas) |
| `404` | Campaign not found | `string`                    |
| `500` | Database error     | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.get(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.get("agent_01HZ2N...");
  ```
</CodeGroup>

### `DELETE /api/v1/campaigns/{id}`

Delete a campaign

Refuses if the campaign is `running`. Pause or stop it first.

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description         | Body     |
| ----- | ------------------- | -------- |
| `204` | Deleted             | —        |
| `404` | Campaign not found  | `string` |
| `409` | Campaign is running | `string` |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.delete(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.delete("agent_01HZ2N...");
  ```
</CodeGroup>

### `GET /api/v1/campaigns/{id}/contacts`

List contacts in a campaign

**Parameters**

| Name     | In    | Type      | Required | Description                                                                             |
| -------- | ----- | --------- | -------- | --------------------------------------------------------------------------------------- |
| `id`     | path  | `string`  | Yes      | Campaign id                                                                             |
| `status` | query | `string`  | No       | Filter by contact status (pending, originated, connected, completed, failed, cancelled) |
| `limit`  | query | `integer` | No       | Page size                                                                               |
| `offset` | query | `integer` | No       | Pagination offset                                                                       |

**Responses**

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

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.list_contacts(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.listContacts("agent_01HZ2N...");
  ```
</CodeGroup>

### `GET /api/v1/campaigns/{id}/events`

Stream campaign events

Server-Sent Events stream of contact-level state transitions (`originated`, `connected`, `failed`, ...). Stays open until the client disconnects.

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description        | Body |
| ----- | ------------------ | ---- |
| `200` | SSE stream         | —    |
| `404` | Campaign not found | —    |

**Example**

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

### `POST /api/v1/campaigns/{id}/pause`

Pause a running campaign

Stops the dispatcher from originating new calls; in-flight calls finish naturally.

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description                                    | Body                        |
| ----- | ---------------------------------------------- | --------------------------- |
| `200` | OK                                             | [`data.Campaign`](#schemas) |
| `404` | Campaign not found                             | `string`                    |
| `409` | Campaign cannot be paused in its current state | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.pause(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.pause("agent_01HZ2N...");
  ```
</CodeGroup>

### `POST /api/v1/campaigns/{id}/resume`

Resume a paused campaign

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description                                     | Body                        |
| ----- | ----------------------------------------------- | --------------------------- |
| `200` | OK                                              | [`data.Campaign`](#schemas) |
| `404` | Campaign not found                              | `string`                    |
| `409` | Campaign cannot be resumed in its current state | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.resume(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.resume("agent_01HZ2N...");
  ```
</CodeGroup>

### `POST /api/v1/campaigns/{id}/start`

Start a campaign

Flips the campaign from `draft`/`paused` to `running`. The dispatcher goroutine begins originating calls subject to per-tenant rate caps.

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description                                     | Body                        |
| ----- | ----------------------------------------------- | --------------------------- |
| `200` | OK                                              | [`data.Campaign`](#schemas) |
| `404` | Campaign not found                              | `string`                    |
| `409` | Campaign cannot be started in its current state | `string`                    |
| `500` | Database error                                  | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.start(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.start("agent_01HZ2N...");
  ```
</CodeGroup>

### `POST /api/v1/campaigns/{id}/stop`

Stop a campaign permanently

Terminal state — no further dispatches, contacts in `pending` move to `cancelled`. Cannot be reversed; create a new campaign to redo the work.

**Parameters**

| Name | In   | Type     | Required | Description |
| ---- | ---- | -------- | -------- | ----------- |
| `id` | path | `string` | Yes      | Campaign id |

**Responses**

| Code  | Description        | Body                        |
| ----- | ------------------ | --------------------------- |
| `200` | OK                 | [`data.Campaign`](#schemas) |
| `404` | Campaign not found | `string`                    |

**Example**

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

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

  client = KatavenClient()  # reads KATAVEN_API_KEY
  client.campaigns.stop(id="agent_01HZ2N...")
  ```

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

  const client = new Kataven();   // reads KATAVEN_API_KEY
  await client.campaigns.stop("agent_01HZ2N...");
  ```
</CodeGroup>