Kataven Hub API — outbound campaigns

Bulk outbound campaigns dialled from CSV with cap-aware concurrency and live SSE metrics. Wrapped by the Python SDK and Node SDK.

Endpoints at a glance

Method	Path	Summary
`GET`	`/api/v1/campaigns`	List campaigns
`POST`	`/api/v1/campaigns`	Create a campaign
`GET`	`/api/v1/campaigns/{id}`	Get a campaign
`DELETE`	`/api/v1/campaigns/{id}`	Delete a campaign
`GET`	`/api/v1/campaigns/{id}/contacts`	List contacts in a campaign
`GET`	`/api/v1/campaigns/{id}/events`	Stream campaign events
`POST`	`/api/v1/campaigns/{id}/pause`	Pause a running campaign
`POST`	`/api/v1/campaigns/{id}/resume`	Resume a paused campaign
`POST`	`/api/v1/campaigns/{id}/start`	Start a campaign
`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

curl https://api.kataven.ai/v1/campaigns \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

const client = new Kataven();   // reads KATAVEN_API_KEY
await client.campaigns.list();

`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`
`400`	Invalid form / CSV	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

from kataven import KatavenClient

client = KatavenClient()  # reads KATAVEN_API_KEY
client.campaigns.create(# body fields go here)

`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`
`404`	Campaign not found	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../contacts \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../events \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

`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`
`404`	Campaign not found	`string`
`409`	Campaign cannot be paused in its current state	`string`

Example

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../pause \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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`
`404`	Campaign not found	`string`
`409`	Campaign cannot be resumed in its current state	`string`

Example

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../resume \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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`
`404`	Campaign not found	`string`
`409`	Campaign cannot be started in its current state	`string`
`500`	Database error	`string`

Example

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../start \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

`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`
`404`	Campaign not found	`string`

Example

curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../stop \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

from kataven import KatavenClient

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

import { Kataven } from "@kataven/server";

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

Get started

Resources

Kataven Hub API — outbound campaigns

Endpoints at a glance

Reference

`GET /api/v1/campaigns`

`POST /api/v1/campaigns`

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

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

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

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

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

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

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

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

​Endpoints at a glance

​Reference

​GET /api/v1/campaigns

​POST /api/v1/campaigns

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

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

​GET /api/v1/campaigns/{id}/contacts

​GET /api/v1/campaigns/{id}/events

​POST /api/v1/campaigns/{id}/pause

​POST /api/v1/campaigns/{id}/resume

​POST /api/v1/campaigns/{id}/start

​POST /api/v1/campaigns/{id}/stop

Endpoints at a glance

Reference

`GET /api/v1/campaigns`

`POST /api/v1/campaigns`

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

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

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

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

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

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

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

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