Skip to main content
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

MethodPathSummary
GET/api/v1/campaignsList campaigns
POST/api/v1/campaignsCreate a campaign
GET/api/v1/campaigns/{id}Get a campaign
DELETE/api/v1/campaigns/{id}Delete a campaign
GET/api/v1/campaigns/{id}/contactsList contacts in a campaign
GET/api/v1/campaigns/{id}/eventsStream campaign events
POST/api/v1/campaigns/{id}/pausePause a running campaign
POST/api/v1/campaigns/{id}/resumeResume a paused campaign
POST/api/v1/campaigns/{id}/startStart a campaign
POST/api/v1/campaigns/{id}/stopStop a campaign permanently

​
Reference

​
GET /api/v1/campaigns

List campaigns Responses
CodeDescriptionBody
200OKobject
500Database errorstring
Example 
curl https://api.kataven.ai/v1/campaigns \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
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
CodeDescriptionBody
201Createddata.Campaign
400Invalid form / CSVstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/campaigns \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{...}'

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

Get a campaign Parameters
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200OKdata.Campaign
404Campaign not foundstring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N... \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

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

Delete a campaign Refuses if the campaign is running. Pause or stop it first. Parameters
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
204Deleted—
404Campaign not foundstring
409Campaign is runningstring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N... \
  -X DELETE \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

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

List contacts in a campaign Parameters
NameInTypeRequiredDescription
idpathstringYesCampaign id
statusquerystringNoFilter by contact status (pending, originated, connected, completed, failed, cancelled)
limitqueryintegerNoPage size
offsetqueryintegerNoPagination offset
Responses
CodeDescriptionBody
200OKobject
500Database errorstring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../contacts \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
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
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200SSE stream—
404Campaign 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
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200OKdata.Campaign
404Campaign not foundstring
409Campaign cannot be paused in its current statestring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../pause \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

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

Resume a paused campaign Parameters
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200OKdata.Campaign
404Campaign not foundstring
409Campaign cannot be resumed in its current statestring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../resume \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
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
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200OKdata.Campaign
404Campaign not foundstring
409Campaign cannot be started in its current statestring
500Database errorstring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../start \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"

​
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
NameInTypeRequiredDescription
idpathstringYesCampaign id
Responses
CodeDescriptionBody
200OKdata.Campaign
404Campaign not foundstring
Example 
curl https://api.kataven.ai/v1/campaigns/agent_01HZ2N.../stop \
  -X POST \
  -H "Authorization: Bearer $KATAVEN_API_KEY"