Developers

Connect your CRM or your own app to your Crang workspace with the REST API, get events as webhooks, or let an AI assistant work with it over MCP. Everything is secured with an API key you create in Settings, Integrations.

Overview

Your workspace has three ways in: a REST API to read and change data, webhooks that call you when something happens, and an MCP server for AI assistants. Each one belongs to a single workspace: the API key decides which.

REST base URL: https://api.crang.ai/v1
MCP server URL: https://mcp.crang.ai/mcp

Versioning

The version is in the path (/v1). New routes and new response fields are added within a version, so ignore fields you do not know. A breaking change ships as a new version, and the old one keeps working for a notice period.

Authentication

Create an API key in Settings, Integrations, and send it on every request as Authorization: Bearer <key>. The key is shown once: store it like a password.

A key belongs to one workspace and acts with the role of the person who created it. The workspace is never part of a request: there is no workspace id to send, and none that could be changed.

Each route needs one scope on the key. Without it the API answers 403. A missing, unknown, revoked or expired key answers 401.

curl "https://api.crang.ai/v1/usage" \
  -H "Authorization: Bearer $CRANG_API_KEY"

Scopes

You choose the scopes when you create a key. A key never gets more than its creator's role allows.

Scope	Allows
calls:read	Read calls, transcripts and results
contacts:read	Read contact lists and contacts
contacts:write	Import contacts and add numbers to the do-not-call list
campaigns:read	Read campaigns and their status
campaigns:write	Create and edit campaigns
campaigns:run	Start, pause, resume and cancel campaigns
agents:read	List agents and read their settings
agents:write	Edit the draft of an agent. Nothing goes live
agents:publish	Publish an agent. Changes go live on real calls
knowledge:read	List knowledge base documents
knowledge:write	Add knowledge base documents. They join every agent, live versions included, so the assistant also needs agents:publish
numbers:read	List phone numbers and the agent that answers each
analytics:read	Read analytics and goal results
usage:read	Read minutes left and usage
mcp	Connect an AI assistant to the MCP server

Errors

Errors are JSON, { "error": { "code": "...", "details": ... } }. Branch on code, never on the HTTP text.

Status	Code	Meaning
400	common.validation	The request is not valid. `details` lists the problems.
401	api_keys.invalid	The key is missing, unknown, revoked or expired.
402	tenant.subscription_suspended	The workspace subscription is suspended.
403	api_keys.scope_missing	The key lacks the scope the route needs (`details.scope`), or the integration is turned off for the workspace.
404	common.not_found	Nothing with that id in your workspace.
429	common.rate_limited	Too many requests. Wait the `Retry-After` header's seconds.

Rate limits

By default 120 requests per minute per key and 600 per minute per workspace across all its keys, shared by the REST API and the MCP server. Beyond that the API answers 429 with a Retry-After header (seconds).

REST API

Requests and answers are JSON unless a route says otherwise. Fields marked required must be sent. In answers, ignore fields you do not know.

Contacts

GET/v1/contact-lists

List contact lists

Required scopecontacts:read

Response 200

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`status`required	"importing" \| "ready" \| "failed"
`contacts`required	integer
`report`required	object \| null
`report.rows`required	integer
`report.imported`required	integer
`report.invalid`required	integer
`report.duplicates`required	integer
`report.suppressed`required	integer
`report.invalidRows`required	object[]
`report.invalidRows[].row`required	integer
`report.invalidRows[].reason`required	"phone_missing" \| "phone_invalid" \| "phone_premium" \| "timezone_invalid" \| "language_invalid"
`variables`required	string[]
`lawfulBasisConfirmedAt`required	string (date-time)
`createdAt`required	string (date-time)

Example request

curl "https://api.crang.ai/v1/contact-lists" \
  -H "Authorization: Bearer $CRANG_API_KEY"

POST/v1/contact-lists

Import a CSV into a new contact list

Answers 202 with the list in importing; poll the list for ready and its report, or subscribe to contact_list.imported.

Required scopecontacts:write

Request body · Multipart form

Field	Type	Description
`file`required	string (binary)	CSV with a header row
`name`required	string
`mapping`required	string	JSON: {"phone": "<column>", "name"?, "language"?, "timezone"?, "externalId"?, "variables"?: {"<call variable>": "<column>"}}
`lawfulBasis`required	"true"	Confirms the workspace may call these people

Response 202

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`status`required	"importing" \| "ready" \| "failed"
`contacts`required	integer
`report`required	object \| null
`report.rows`required	integer
`report.imported`required	integer
`report.invalid`required	integer
`report.duplicates`required	integer
`report.suppressed`required	integer
`report.invalidRows`required	object[]
`report.invalidRows[].row`required	integer
`report.invalidRows[].reason`required	"phone_missing" \| "phone_invalid" \| "phone_premium" \| "timezone_invalid" \| "language_invalid"
`variables`required	string[]
`lawfulBasisConfirmedAt`required	string (date-time)
`createdAt`required	string (date-time)

Example request

curl -X POST "https://api.crang.ai/v1/contact-lists" \
  -H "Authorization: Bearer $CRANG_API_KEY" \
  -F file='@contacts.csv' \
  -F name='Spring customers' \
  -F mapping='{"phone": "Phone"}' \
  -F lawfulBasis='true'

GET/v1/contact-lists/{id}

Get a contact list

Required scopecontacts:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`status`required	"importing" \| "ready" \| "failed"
`contacts`required	integer
`report`required	object \| null
`report.rows`required	integer
`report.imported`required	integer
`report.invalid`required	integer
`report.duplicates`required	integer
`report.suppressed`required	integer
`report.invalidRows`required	object[]
`report.invalidRows[].row`required	integer
`report.invalidRows[].reason`required	"phone_missing" \| "phone_invalid" \| "phone_premium" \| "timezone_invalid" \| "language_invalid"
`variables`required	string[]
`lawfulBasisConfirmedAt`required	string (date-time)
`createdAt`required	string (date-time)

Example request

curl "https://api.crang.ai/v1/contact-lists/<id>" \
  -H "Authorization: Bearer $CRANG_API_KEY"

GET/v1/contact-lists/{id}/contacts

List the contacts of a list

Required scopecontacts:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path
`cursor`	string (uuid) · query
`limit`	integer · query = 50

Response 200

Field	Type	Description
`items`required	object[]
`items[].id`required	string (uuid)
`items[].phone`required	string
`items[].name`required	string \| null
`items[].language`required	string \| null
`items[].timezone`required	string \| null
`items[].externalId`required	string \| null
`items[].variables`required	object<string, string>
`items[].createdAt`required	string (date-time)
`nextCursor`required	string (uuid) \| null

Example request

curl "https://api.crang.ai/v1/contact-lists/<id>/contacts" \
  -H "Authorization: Bearer $CRANG_API_KEY"

POST/v1/dnc

Add numbers to the do-not-call list

400 with the numbers that are not valid in details.invalid.

Required scopecontacts:write

Request body · JSON

Field	Type	Description
`phones`required	string[]
`source`required	"manual" \| "csv"
`note`	string

Response 200

Field	Type	Description
`added`required	integer

Example request

curl -X POST "https://api.crang.ai/v1/dnc" \
  -H "Authorization: Bearer $CRANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones":["string"],"source":"manual"}'

POST/v1/contacts/{id}/erase

Erase a person (GDPR erasure request)

Deletes every contact with this contact's number, in every list, and clears the number, transcript, summary, captured data and free-text analysis of their calls (outcome, minutes and goal results stay in the counts). A do-not-call entry for the number stays as a suppression record without the number, so the number is still not called. Only for a key whose creator is the workspace owner (403 otherwise). 409 contacts.erase_call_recent while a call with the person runs or ended less than 10 minutes ago.

Required scopecontacts:write

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`contacts`required	integer
`calls`required	integer

Example request

curl -X POST "https://api.crang.ai/v1/contacts/<id>/erase" \
  -H "Authorization: Bearer $CRANG_API_KEY"

Campaigns

GET/v1/campaigns

List campaigns

Required scopecampaigns:read

Response 200

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)
`listIds`required	string (uuid)[]
`phoneNumberIds`required	string (uuid)[]
`startsAt`required	string (date-time) \| null
`settings`required	object
`settings.timezone`required	string
`settings.windows`required	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`required	integer
`settings.retryMinutes`required	integer
`settings.retryOn`required	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`required	integer
`settings.callsPerMinute`required	integer
`settings.ringTimeoutSeconds`required	integer
`settings.maxDurationSeconds`required	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.
`id`required	string (uuid)
`status`required	"draft" \| "scheduled" \| "running" \| "paused" \| "completed" \| "cancelled"
`pauseReason`required	"manual" \| "minutes" \| "protection" \| null
`createdAt`required	string (date-time)
`startedAt`required	string (date-time) \| null
`endedAt`required	string (date-time) \| null
`progress`required	object<string, integer>
`stats`required	object
`stats.calls`required	integer
`stats.answered`required	integer
`stats.successful`required	integer
`stats.seconds`required	integer
`stats.hourly`required	object[]
`stats.hourly[].hour`required	string (date-time)
`stats.hourly[].calls`required	integer

Example request

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

GET/v1/campaigns/{id}

Get a campaign

Required scopecampaigns:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)
`listIds`required	string (uuid)[]
`phoneNumberIds`required	string (uuid)[]
`startsAt`required	string (date-time) \| null
`settings`required	object
`settings.timezone`required	string
`settings.windows`required	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`required	integer
`settings.retryMinutes`required	integer
`settings.retryOn`required	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`required	integer
`settings.callsPerMinute`required	integer
`settings.ringTimeoutSeconds`required	integer
`settings.maxDurationSeconds`required	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.
`id`required	string (uuid)
`status`required	"draft" \| "scheduled" \| "running" \| "paused" \| "completed" \| "cancelled"
`pauseReason`required	"manual" \| "minutes" \| "protection" \| null
`createdAt`required	string (date-time)
`startedAt`required	string (date-time) \| null
`endedAt`required	string (date-time) \| null
`progress`required	object<string, integer>
`stats`required	object
`stats.calls`required	integer
`stats.answered`required	integer
`stats.successful`required	integer
`stats.seconds`required	integer
`stats.hourly`required	object[]
`stats.hourly[].hour`required	string (date-time)
`stats.hourly[].calls`required	integer

Example request

curl "https://api.crang.ai/v1/campaigns/<id>" \
  -H "Authorization: Bearer $CRANG_API_KEY"

POST/v1/campaigns/{id}/start

Start a campaign

Required scopecampaigns:run

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)
`listIds`required	string (uuid)[]
`phoneNumberIds`required	string (uuid)[]
`startsAt`required	string (date-time) \| null
`settings`required	object
`settings.timezone`required	string
`settings.windows`required	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`required	integer
`settings.retryMinutes`required	integer
`settings.retryOn`required	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`required	integer
`settings.callsPerMinute`required	integer
`settings.ringTimeoutSeconds`required	integer
`settings.maxDurationSeconds`required	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.
`id`required	string (uuid)
`status`required	"draft" \| "scheduled" \| "running" \| "paused" \| "completed" \| "cancelled"
`pauseReason`required	"manual" \| "minutes" \| "protection" \| null
`createdAt`required	string (date-time)
`startedAt`required	string (date-time) \| null
`endedAt`required	string (date-time) \| null
`progress`required	object<string, integer>
`stats`required	object
`stats.calls`required	integer
`stats.answered`required	integer
`stats.successful`required	integer
`stats.seconds`required	integer
`stats.hourly`required	object[]
`stats.hourly[].hour`required	string (date-time)
`stats.hourly[].calls`required	integer

Example request

curl -X POST "https://api.crang.ai/v1/campaigns/<id>/start" \
  -H "Authorization: Bearer $CRANG_API_KEY"

POST/v1/campaigns/{id}/pause

Pause a campaign

Required scopecampaigns:run

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)
`listIds`required	string (uuid)[]
`phoneNumberIds`required	string (uuid)[]
`startsAt`required	string (date-time) \| null
`settings`required	object
`settings.timezone`required	string
`settings.windows`required	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`required	integer
`settings.retryMinutes`required	integer
`settings.retryOn`required	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`required	integer
`settings.callsPerMinute`required	integer
`settings.ringTimeoutSeconds`required	integer
`settings.maxDurationSeconds`required	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.
`id`required	string (uuid)
`status`required	"draft" \| "scheduled" \| "running" \| "paused" \| "completed" \| "cancelled"
`pauseReason`required	"manual" \| "minutes" \| "protection" \| null
`createdAt`required	string (date-time)
`startedAt`required	string (date-time) \| null
`endedAt`required	string (date-time) \| null
`progress`required	object<string, integer>
`stats`required	object
`stats.calls`required	integer
`stats.answered`required	integer
`stats.successful`required	integer
`stats.seconds`required	integer
`stats.hourly`required	object[]
`stats.hourly[].hour`required	string (date-time)
`stats.hourly[].calls`required	integer

Example request

curl -X POST "https://api.crang.ai/v1/campaigns/<id>/pause" \
  -H "Authorization: Bearer $CRANG_API_KEY"

POST/v1/campaigns/{id}/resume

Resume a paused campaign

Required scopecampaigns:run

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)
`listIds`required	string (uuid)[]
`phoneNumberIds`required	string (uuid)[]
`startsAt`required	string (date-time) \| null
`settings`required	object
`settings.timezone`required	string
`settings.windows`required	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`required	integer
`settings.retryMinutes`required	integer
`settings.retryOn`required	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`required	integer
`settings.callsPerMinute`required	integer
`settings.ringTimeoutSeconds`required	integer
`settings.maxDurationSeconds`required	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.
`id`required	string (uuid)
`status`required	"draft" \| "scheduled" \| "running" \| "paused" \| "completed" \| "cancelled"
`pauseReason`required	"manual" \| "minutes" \| "protection" \| null
`createdAt`required	string (date-time)
`startedAt`required	string (date-time) \| null
`endedAt`required	string (date-time) \| null
`progress`required	object<string, integer>
`stats`required	object
`stats.calls`required	integer
`stats.answered`required	integer
`stats.successful`required	integer
`stats.seconds`required	integer
`stats.hourly`required	object[]
`stats.hourly[].hour`required	string (date-time)
`stats.hourly[].calls`required	integer

Example request

curl -X POST "https://api.crang.ai/v1/campaigns/<id>/resume" \
  -H "Authorization: Bearer $CRANG_API_KEY"

Calls

GET/v1/calls

List calls

Required scopecalls:read

Parameters

Field	Type	Description
`cursor`	string (uuid) · query
`limit`	integer · query = 50
`direction`	"inbound" \| "outbound" · query
`agentId`	string (uuid) · query
`campaignId`	string (uuid) · query
`contactId`	string (uuid) · query
`phoneNumberId`	string (uuid) · query
`outcome`	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed" · query
`success`	"all_met" \| "any_failed" \| "unknown" · query
`from`	string (date-time) · query
`to`	string (date-time) · query
`minSeconds`	integer · query
`maxSeconds`	integer · query
`q`	string · query
`transferred`	string · query
`cutOff`	string · query

Response 200

Field	Type	Description
`items`required	object[]
`items[].id`required	string (uuid)
`items[].direction`required	"inbound" \| "outbound"
`items[].status`required	"active" \| "ended"
`items[].outcome`required	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed" \| null
`items[].success`required	"all_met" \| "any_failed" \| "unknown" \| null
`items[].agent`required	object \| null
`items[].agent.id`required	string (uuid)
`items[].agent.name`required	string
`items[].campaign`required	object \| null
`items[].campaign.id`required	string (uuid)
`items[].campaign.name`required	string
`items[].contact`required	object \| null
`items[].contact.id`required	string (uuid)
`items[].contact.name`required	string \| null
`items[].phone`required	string
`items[].line`required	string \| null
`items[].seconds`required	integer \| null
`items[].startedAt`required	string (date-time)
`items[].endedAt`required	string (date-time) \| null
`items[].transferred`required	boolean
`items[].cutOff`required	boolean	True when an answered call ended without the agent closing it or handing it off: the other side hung up or the line dropped.
`nextCursor`required	string (uuid) \| null

Example request

curl "https://api.crang.ai/v1/calls" \
  -H "Authorization: Bearer $CRANG_API_KEY"

GET/v1/calls/{id}

Get a call

Required scopecalls:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`id`required	string (uuid)
`direction`required	"inbound" \| "outbound"
`status`required	"active" \| "ended"
`outcome`required	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed" \| null
`success`required	"all_met" \| "any_failed" \| "unknown" \| null
`agent`required	object \| null
`agent.id`required	string (uuid)
`agent.name`required	string
`campaign`required	object \| null
`campaign.id`required	string (uuid)
`campaign.name`required	string
`contact`required	object \| null
`contact.id`required	string (uuid)
`contact.name`required	string \| null
`phone`required	string
`line`required	string \| null
`seconds`required	integer \| null
`startedAt`required	string (date-time)
`endedAt`required	string (date-time) \| null
`transferred`required	boolean
`cutOff`required	boolean	True when an answered call ended without the agent closing it or handing it off: the other side hung up or the line dropped.
`summary`required	string \| null
`transcript`required	object[]
`transcript[].role`required	"user" \| "agent"
`transcript[].text`required	string
`transcript[].atSeconds`required	number
`capturedData`required	object[]
`capturedData[].name`required	string
`capturedData[].value`required	any
`criteria`required	object[]
`criteria[].name`required	string
`criteria[].result`required	"success" \| "failure" \| "unknown"
`criteria[].rationale`required	string
`goals`required	object[]
`goals[].name`required	string
`goals[].status`required	"reached" \| "not_reached" \| "unknown" \| "not_rated"
`goals[].value`required	string \| number \| boolean
`hasAudio`required	boolean

Example request

curl "https://api.crang.ai/v1/calls/<id>" \
  -H "Authorization: Bearer $CRANG_API_KEY"

GET/v1/calls/{id}/transcript

Download the transcript (txt or json)

Required scopecalls:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path
`format`	"txt" \| "json" · query = "txt"

Example request

curl "https://api.crang.ai/v1/calls/<id>/transcript" \
  -H "Authorization: Bearer $CRANG_API_KEY"

Agents

GET/v1/agents

List agents

Required scopeagents:read

Response 200

Field	Type	Description
`slots`required	object
`slots.used`required	integer
`slots.total`required	integer
`agents`required	object[]
`agents[].id`required	string (uuid)
`agents[].name`required	string
`agents[].direction`required	"inbound" \| "outbound" \| "both"
`agents[].status`required	"draft_only" \| "published" \| "unpublished_changes"
`agents[].voiceId`required	string (uuid) \| null
`agents[].languages`required	string[]
`agents[].currentVersion`required	integer \| null
`agents[].publishedAt`required	string (date-time) \| null

Example request

curl "https://api.crang.ai/v1/agents" \
  -H "Authorization: Bearer $CRANG_API_KEY"

GET/v1/agents/{id}

Get an agent

Required scopeagents:read

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Response 200

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`direction`required	"inbound" \| "outbound" \| "both"
`status`required	"draft_only" \| "published" \| "unpublished_changes"
`voiceId`required	string (uuid) \| null
`languages`required	string[]
`currentVersion`required	integer \| null
`publishedAt`required	string (date-time) \| null
`templateKey`required	string \| null
`createdAt`required	string (date-time)
`config`required	object
`config.basics`required	object
`config.basics.voiceId`required	string (uuid) \| null
`config.basics.stability`required	number
`config.basics.speed`required	number
`config.basics.languages`required	object[]
`config.basics.callVariables`required	object[]
`config.rules`required	object
`config.rules.purpose`required	string
`config.rules.tone`required	string
`config.rules.alwaysSay`required	string[]
`config.rules.neverSay`required	string[]
`config.rules.transfers`required	object[]
`config.rules.endCallRules`required	string[]
`config.rules.dataToCapture`required	object[]
`config.rules.goals`required	object[]
`config.rules.callHandling`required	object
`config.rules.voicemailMessage`required	string
`config.rules.additionalInstructions`required	string
`config.workflow`required	object
`config.workflow.steps`required	object[]
`config.openingHours`	object
`config.openingHours.enabled`required	boolean
`config.openingHours.timezone`required	string
`config.openingHours.windows`required	object[]
`config.openingHours.outside`required	"message" \| "transfer" \| "reject"
`config.openingHours.transferNumber`required	string \| null
`knowledgeBase`required	string (uuid)[]
`revision`required	integer
`draftUpdatedAt`required	string (date-time)
`draftBasedOnVersion`required	integer \| null
`dataCollectionLimit`required	integer
`inboundPersonalization`required	boolean

Example request

curl "https://api.crang.ai/v1/agents/<id>" \
  -H "Authorization: Bearer $CRANG_API_KEY"

PATCH/v1/agents/{id}

Edit the agent's draft

Changes land in the draft only; callers keep talking to the published version until a publish. The exception is inboundPersonalization (off by default), which applies from the next inbound call: when on, a caller whose number the carrier fully verified gets the call variables of their matching contact. Send the revision from the last read (409 on a stale one).

Required scopeagents:write

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Request body · JSON

Field	Type	Description
`revision`required	integer
`name`	string
`config`	object
`config.basics`required	object
`config.basics.voiceId`required	string (uuid) \| null
`config.basics.stability`required	number
`config.basics.speed`required	number
`config.basics.languages`required	object[]
`config.basics.callVariables`required	object[]
`config.rules`required	object
`config.rules.purpose`required	string
`config.rules.tone`required	string
`config.rules.alwaysSay`required	string[]
`config.rules.neverSay`required	string[]
`config.rules.transfers`required	object[]
`config.rules.endCallRules`required	string[]
`config.rules.dataToCapture`required	object[]
`config.rules.goals`required	object[]
`config.rules.callHandling`required	object
`config.rules.voicemailMessage`required	string
`config.rules.additionalInstructions`required	string
`config.workflow`required	object
`config.workflow.steps`required	object[]
`config.openingHours`	object
`config.openingHours.enabled`required	boolean
`config.openingHours.timezone`required	string
`config.openingHours.windows`required	object[]
`config.openingHours.outside`required	"message" \| "transfer" \| "reject"
`config.openingHours.transferNumber`required	string \| null
`knowledgeBase`	string (uuid)[]
`inboundPersonalization`	boolean

Response 200

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`direction`required	"inbound" \| "outbound" \| "both"
`status`required	"draft_only" \| "published" \| "unpublished_changes"
`voiceId`required	string (uuid) \| null
`languages`required	string[]
`currentVersion`required	integer \| null
`publishedAt`required	string (date-time) \| null
`templateKey`required	string \| null
`createdAt`required	string (date-time)
`config`required	object
`config.basics`required	object
`config.basics.voiceId`required	string (uuid) \| null
`config.basics.stability`required	number
`config.basics.speed`required	number
`config.basics.languages`required	object[]
`config.basics.callVariables`required	object[]
`config.rules`required	object
`config.rules.purpose`required	string
`config.rules.tone`required	string
`config.rules.alwaysSay`required	string[]
`config.rules.neverSay`required	string[]
`config.rules.transfers`required	object[]
`config.rules.endCallRules`required	string[]
`config.rules.dataToCapture`required	object[]
`config.rules.goals`required	object[]
`config.rules.callHandling`required	object
`config.rules.voicemailMessage`required	string
`config.rules.additionalInstructions`required	string
`config.workflow`required	object
`config.workflow.steps`required	object[]
`config.openingHours`	object
`config.openingHours.enabled`required	boolean
`config.openingHours.timezone`required	string
`config.openingHours.windows`required	object[]
`config.openingHours.outside`required	"message" \| "transfer" \| "reject"
`config.openingHours.transferNumber`required	string \| null
`knowledgeBase`required	string (uuid)[]
`revision`required	integer
`draftUpdatedAt`required	string (date-time)
`draftBasedOnVersion`required	integer \| null
`dataCollectionLimit`required	integer
`inboundPersonalization`required	boolean

Example request

curl -X PATCH "https://api.crang.ai/v1/agents/<id>" \
  -H "Authorization: Bearer $CRANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision":0}'

POST/v1/agents/{id}/publish

Publish the draft: live calls use it from now on

Required scopeagents:publish

Parameters

Field	Type	Description
`id`required	string (uuid) · path

Request body · JSON

Field	Type	Description
`note`	string
`revision`	integer

Response 200

Field	Type	Description
`id`required	string (uuid)
`name`required	string
`direction`required	"inbound" \| "outbound" \| "both"
`status`required	"draft_only" \| "published" \| "unpublished_changes"
`voiceId`required	string (uuid) \| null
`languages`required	string[]
`currentVersion`required	integer \| null
`publishedAt`required	string (date-time) \| null
`templateKey`required	string \| null
`createdAt`required	string (date-time)
`config`required	object
`config.basics`required	object
`config.basics.voiceId`required	string (uuid) \| null
`config.basics.stability`required	number
`config.basics.speed`required	number
`config.basics.languages`required	object[]
`config.basics.callVariables`required	object[]
`config.rules`required	object
`config.rules.purpose`required	string
`config.rules.tone`required	string
`config.rules.alwaysSay`required	string[]
`config.rules.neverSay`required	string[]
`config.rules.transfers`required	object[]
`config.rules.endCallRules`required	string[]
`config.rules.dataToCapture`required	object[]
`config.rules.goals`required	object[]
`config.rules.callHandling`required	object
`config.rules.voicemailMessage`required	string
`config.rules.additionalInstructions`required	string
`config.workflow`required	object
`config.workflow.steps`required	object[]
`config.openingHours`	object
`config.openingHours.enabled`required	boolean
`config.openingHours.timezone`required	string
`config.openingHours.windows`required	object[]
`config.openingHours.outside`required	"message" \| "transfer" \| "reject"
`config.openingHours.transferNumber`required	string \| null
`knowledgeBase`required	string (uuid)[]
`revision`required	integer
`draftUpdatedAt`required	string (date-time)
`draftBasedOnVersion`required	integer \| null
`dataCollectionLimit`required	integer
`inboundPersonalization`required	boolean

Example request

curl -X POST "https://api.crang.ai/v1/agents/<id>/publish" \
  -H "Authorization: Bearer $CRANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Usage

GET/v1/usage

Get usage

Required scopeusage:read

Response 200

Field	Type	Description
`status`required	"pending_payment" \| "setup" \| "active" \| "past_due" \| "suspended" \| "cancelled" \| "pending_deletion"
`billingCycle`required	"monthly" \| "annual" \| null
`month`required	object \| null
`month.leftSeconds`required	integer
`month.grantedSeconds`required	integer
`month.endsAt`required	string (date-time)
`packSeconds`required	integer
`overdraftSeconds`required	integer
`liveCalls`required	integer
`callLimit`required	integer
`packPrice`required	object \| null
`packPrice.amount`required	integer
`packPrice.currency`required	string

Example request

curl "https://api.crang.ai/v1/usage" \
  -H "Authorization: Bearer $CRANG_API_KEY"

Webhooks

A webhook is an HTTPS address of yours. Crang sends it a POST when something happens in the workspace. Add endpoints in Settings, Integrations, choose their events and copy the signing secret.

The request

Every event has the same body, sent as JSON with the headers Content-Type, User-Agent: Crang-Webhooks/1.0 and Crang-Signature. Only the fields of data differ.

Field	Type	Description
`id`required	string	Event id. The same on every retry and resend: drop duplicates by it.
`type`required	string	The event type.
`createdAt`required	string (date-time)	When the event was recorded.
`data`required	object	The fields of the event, listed below.

Verify the signature

Crang-Signature is t={unix seconds},v1={hex}, where v1 is the HMAC-SHA256 of {t}.{raw body} with your endpoint's signing secret (whsec_...). During a secret rotation there are two v1 values for 24 hours: accept any match.

Compute it on the raw body, compare in constant time and reject a t older than 5 minutes.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody, header, secret) {
  const parts = header.split(",").map((p) => p.split("="));
  const t = parts.find(([k]) => k === "t")?.[1];
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return parts
    .filter(([k]) => k === "v1")
    .some(([, v]) => v?.length === expected.length && timingSafeEqual(Buffer.from(v), Buffer.from(expected)));
}

Delivery and retries

Answer with any 2xx within 10 seconds; only the status is read and redirects are not followed. Otherwise Crang retries 6 times, after 1 min, 5 min, 30 min, 2 h, 6 h, 15 h, about 24 hours in all, and then marks the delivery failed. An endpoint whose deliveries keep failing is turned off and the owners are emailed. Delivery is at least once.

While the workspace is suspended nothing is delivered, except the one tenant.suspended event.

Settings, Integrations shows the recent deliveries with their status, attempts and payload. You can resend one, or send a test event (webhook.test) to a single endpoint.

Events

Pick the events each endpoint receives. webhook.test goes only to the endpoint you test.

`call.completed`

A call was answered or reached voicemail, and its result is stored.

Field	Type	Description
`callId`required	string (uuid)	The call. Use it with GET /v1/calls/{id}
`direction`required	"inbound" \| "outbound"
`outcome`required	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed"	How the call ended
`seconds`required	integer	Length of the call in seconds
`billedSeconds`required	integer	Seconds taken from your minutes
`startedAt`required	string (date-time)
`cutOff`required	boolean	True when an answered call ended without the agent closing it or handing it off: the other side hung up or the line dropped.

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "call.completed",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "callId": "7b0e5f1c-3a52-4d0e-9a55-2f1d6f0c9a10",
    "direction": "outbound",
    "outcome": "answered",
    "seconds": 94,
    "billedSeconds": 94,
    "startedAt": "2026-03-02T14:05:09.000Z",
    "cutOff": false
  }
}

`call.failed`

A call ended without being answered: no answer, busy or failed.

Field	Type	Description
`callId`required	string (uuid)	The call. Use it with GET /v1/calls/{id}
`direction`required	"inbound" \| "outbound"
`outcome`required	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed"	How the call ended
`seconds`required	integer	Length of the call in seconds
`billedSeconds`required	integer	Seconds taken from your minutes
`startedAt`required	string (date-time)
`cutOff`required	boolean	True when an answered call ended without the agent closing it or handing it off: the other side hung up or the line dropped.

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "call.failed",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "callId": "7b0e5f1c-3a52-4d0e-9a55-2f1d6f0c9a10",
    "direction": "outbound",
    "outcome": "no_answer",
    "seconds": 0,
    "billedSeconds": 0,
    "startedAt": "2026-03-02T14:05:09.000Z",
    "cutOff": false
  }
}

`campaign.completed`

A campaign has nothing left to dial or to wait for.

Field	Type	Description
`campaignId`required	string (uuid)	The campaign. Use it with GET /v1/campaigns/{id}

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "campaign.completed",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "campaignId": "7b0e5f1c-3a52-4d0e-9a55-2f1d6f0c9a10"
  }
}

`contact_list.imported`

A CSV import finished, ready or failed.

Field	Type	Description
`listId`required	string (uuid)	The list. Use it with GET /v1/contact-lists/{id}
`status`required	"ready" \| "failed"
`imported`required	integer	Contacts added
`invalid`required	integer	Rows without a usable phone number
`duplicates`required	integer	Rows dropped as duplicates
`suppressed`required	integer	Rows dropped because the number is on the do-not-call list

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "contact_list.imported",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "listId": "7b0e5f1c-3a52-4d0e-9a55-2f1d6f0c9a10",
    "status": "ready",
    "imported": 940,
    "invalid": 12,
    "duplicates": 31,
    "suppressed": 17
  }
}

`usage.threshold_reached`

The monthly minutes passed 80, 95 or 100 percent.

Field	Type	Description
`threshold`required	"80" \| "95" \| "100" \| "zero"	Share of the monthly minutes used, or zero left

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "usage.threshold_reached",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "threshold": "80"
  }
}

`usage.exhausted`

The monthly minutes ran out.

Field	Type	Description
`threshold`required	"80" \| "95" \| "100" \| "zero"	Share of the monthly minutes used, or zero left

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "usage.exhausted",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "threshold": "zero"
  }
}

`tenant.suspended`

The workspace was suspended: calls stop and nothing else is delivered.

Field	Type	Description
`status`required	"pending_payment" \| "setup" \| "active" \| "past_due" \| "suspended" \| "cancelled" \| "pending_deletion"
`previousStatus`required	"pending_payment" \| "setup" \| "active" \| "past_due" \| "suspended" \| "cancelled" \| "pending_deletion"

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "tenant.suspended",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "status": "suspended",
    "previousStatus": "active"
  }
}

`tenant.reactivated`

The workspace is active again.

Field	Type	Description
`status`required	"pending_payment" \| "setup" \| "active" \| "past_due" \| "suspended" \| "cancelled" \| "pending_deletion"
`previousStatus`required	"pending_payment" \| "setup" \| "active" \| "past_due" \| "suspended" \| "cancelled" \| "pending_deletion"

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "tenant.reactivated",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "status": "active",
    "previousStatus": "suspended"
  }
}

`webhook.test`

Sent by Send test event, to that one endpoint only.

Field	Type	Description
`endpointId`required	string (uuid)	The endpoint the test was sent to

Example payload

{
  "id": "evt_0f1e2d3c4b5a69788796a5b4c3d2e1f0",
  "type": "webhook.test",
  "createdAt": "2026-03-02T14:05:09.000Z",
  "data": {
    "endpointId": "7b0e5f1c-3a52-4d0e-9a55-2f1d6f0c9a10"
  }
}

MCP

The MCP server lets an AI assistant work with your workspace as the API key allows, and nothing more. Every action is recorded in the audit log. It is Streamable HTTP, without sessions.

Authentication

Send the key as Authorization: Bearer <key>. The key needs the mcp scope plus the scopes of the tools you want to use. The assistant sees only the tools its key allows; any other is answered as not found. Requests count against the same rate limits as the REST API.

Connect an AI assistant

Add the server to the assistant's MCP configuration and replace YOUR_API_KEY with your key. Agent edits land in the draft; nothing goes live until publish_agent.

{
  "mcpServers": {
    "crang": {
      "url": "https://mcp.crang.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Tools

41 tools. Each needs all the scopes listed.

Calls

`list_calls`

Read

Find calls

Read only. Lists calls, newest first, with outcome, goal result, agent, campaign, contact and duration. Filter by direction, agent, campaign, contact, phone number, outcome, goal result (success), time range (from/to, ISO date-time), length in seconds, transfers, cut-off calls (cutOff) or a phone/name search (q). Paginate with cursor.

Scopescalls:read

Arguments

Field	Type	Description
`cursor`	string (uuid)	`nextCursor` of the previous page
`direction`	"inbound" \| "outbound"
`agentId`	string (uuid)
`campaignId`	string (uuid)
`contactId`	string (uuid)
`phoneNumberId`	string (uuid)
`outcome`	"answered" \| "voicemail" \| "no_answer" \| "busy" \| "failed"
`success`	"all_met" \| "any_failed" \| "unknown"
`from`	string (date-time)
`to`	string (date-time)
`minSeconds`	integer
`maxSeconds`	integer
`q`	string
`limit`	integer = 50
`transferred`	boolean	Handed to a person or another agent
`cutOff`	boolean	True when an answered call ended without the agent closing it or handing it off: the other side hung up or the line dropped.

`get_call`

Read

Get a call

Read only. One call with its summary, full transcript (caller and agent turns), captured data and goal results.

Scopescalls:read

Arguments

Field	Type	Description
`callId`required	string (uuid)

Contacts

`list_contact_lists`

Read

List contact lists

Read only. Contact lists with their status (importing, ready, failed), contact count and import report.

Scopescontacts:read

Arguments

No arguments.

`get_contact_list`

Read

Get a contact list

Read only. One contact list with its status and import report (imported, invalid, duplicate and do-not-call rows). Use it to follow an import.

Scopescontacts:read

Arguments

Field	Type	Description
`listId`required	string (uuid)

`list_contacts`

Read

List contacts

Read only. The contacts of one list, newest first. Paginate with cursor.

Scopescontacts:read

Arguments

Field	Type	Description
`listId`required	string (uuid)
`cursor`	string (uuid)	`nextCursor` of the previous page
`limit`	integer = 50

`search_do_not_call`

Read

Search the do-not-call list

Read only. Numbers the workspace never calls, newest first; query matches phone digits.

Scopescontacts:read

Arguments

Field	Type	Description
`query`	string
`cursor`	string (uuid)	`nextCursor` of the previous page
`limit`	integer = 50

`import_contacts`

Changes data

Import contacts

Changes data. Creates a new contact list from rows (objects of column name to value), with the same checks as a CSV import in the app: phone numbers are normalized, invalid and duplicate rows are skipped and do-not-call numbers suppressed. mapping names the column for each contact field and for each call variable; other columns are ignored. At most 5,000 rows and 100,000 values (rows × mapped columns) per call, and 30 call variables: for more rows, call it again (each call makes its own list). Only for people the workspace may lawfully call (lawfulBasis: true records that confirmation). Returns the list in importing; call get_contact_list for the report.

Scopescontacts:write

Arguments

Field	Type	Description
`name`required	string
`rows`required	object<string, string \| number \| boolean \| null>[]
`mapping`required	object
`mapping.phone`required	string
`mapping.name`	string
`mapping.language`	string
`mapping.timezone`	string
`mapping.externalId`	string
`mapping.variables`	object<string, string> = {}
`lawfulBasis`required	true

`add_to_do_not_call`

Changes data

Add numbers to do-not-call

Changes data. Adds phone numbers to the do-not-call list; campaigns skip them from now on. Any invalid number refuses the whole request (details.invalid).

Scopescontacts:write

Arguments

Field	Type	Description
`phones`required	string[]
`note`	string

Campaigns

`list_campaigns`

Read

List campaigns

Read only. Outbound campaigns with status, progress by contact state and call stats.

Scopescampaigns:read

Arguments

No arguments.

`get_campaign`

Read

Get campaign status

Read only. One campaign: status, pause reason, settings, progress and calls in the last 24 hours.

Scopescampaigns:read

Arguments

Field	Type	Description
`campaignId`required	string (uuid)

`create_campaign`

Changes data

Create a campaign

Changes data. Creates a draft outbound campaign (nothing is dialed until start_campaign). Settings default to weekday business hours in the workspace time zone.

Scopescampaigns:write

Arguments

Field	Type	Description
`name`required	string
`agentId`required	string (uuid)	An agent with a published version
`listIds`required	string (uuid)[]	Contact lists to call
`phoneNumberIds`required	string (uuid)[]	Workspace numbers to call from
`startsAt`	string (date-time) \| null	When dialing may start after start_campaign; null or left out: at once
`settings`required	object	Dialing settings; anything left out keeps its current or default value
`settings.timezone`	string
`settings.windows`	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`	integer
`settings.retryMinutes`	integer
`settings.retryOn`	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`	integer
`settings.callsPerMinute`	integer
`settings.ringTimeoutSeconds`	integer
`settings.maxDurationSeconds`	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.

`update_campaign`

Changes data

Edit a campaign

Changes data. Edits a draft, scheduled or paused campaign; fields left out keep their value. Scheduled and paused campaigns keep their agent and lists.

Scopescampaigns:write

Arguments

Field	Type	Description
`campaignId`required	string (uuid)
`name`	string
`agentId`	string (uuid)	An agent with a published version
`listIds`	string (uuid)[]	Contact lists to call
`phoneNumberIds`	string (uuid)[]	Workspace numbers to call from
`startsAt`	string (date-time) \| null	When dialing may start after start_campaign; null or left out: at once
`settings`	object	Dialing settings; anything left out keeps its current or default value
`settings.timezone`	string
`settings.windows`	object[]
`settings.windows[].days`required	integer[]
`settings.windows[].start`required	string
`settings.windows[].end`required	string
`settings.maxAttempts`	integer
`settings.retryMinutes`	integer
`settings.retryOn`	"no_answer" \| "busy" \| "failed" \| "voicemail" \| "cut_off"[]
`settings.maxConcurrent`	integer
`settings.callsPerMinute`	integer
`settings.ringTimeoutSeconds`	integer
`settings.maxDurationSeconds`	integer
`settings.protection`	object	Protection overrides: pause automatically, minute limit, slow start and stop values
`settings.protection.autoPause`	boolean	Pause the campaign automatically when its recent calls look bad. Default false: the campaign only shows its metrics. The minute limit applies either way.
`settings.protection.minuteLimit`	integer \| null	Most minutes this campaign may use (debited plus in progress); null or left out: no limit
`settings.protection.warmup`	boolean	Slow start: the first calls run a few at a time. Default false.
`settings.protection.stops`	object<string, integer \| null>	Per indicator, the percent of the last finished calls at which the campaign pauses (answer_rate: pauses when under it); null turns that stop off. technical_failures is between 5 and 60 and cannot be null. Left out: the workspace default.

`start_campaign`

Goes live

Start a campaign

Changes data. Starts a draft campaign: real calls go out (now, or at startsAt) and use minutes. Needs a published agent, a phone number and contacts.

Scopescampaigns:run

Arguments

Field	Type	Description
`campaignId`required	string (uuid)

`pause_campaign`

Changes data

Pause a campaign

Changes data. Pauses a running or scheduled campaign; calls in progress finish.

Scopescampaigns:run

Arguments

Field	Type	Description
`campaignId`required	string (uuid)

`resume_campaign`

Goes live

Resume a campaign

Changes data. Resumes a paused campaign: dialing continues.

Scopescampaigns:run

Arguments

Field	Type	Description
`campaignId`required	string (uuid)

`cancel_campaign`

Changes data

Cancel a campaign

Changes data, cannot be undone. Cancels a campaign for good; it never dials again.

Scopescampaigns:run

Arguments

Field	Type	Description
`campaignId`required	string (uuid)

`duplicate_campaign`

Changes data

Duplicate a campaign

Changes data. A new draft with the same agent, numbers and settings: the same lists (all) or a new list of the contacts not reached yet (not_reached, named listName).

Scopescampaigns:write

Arguments

Field	Type	Description
`campaignId`required	string (uuid)
`contacts`required	"all" \| "not_reached"
`listName`	string

Agents

`list_agents`

Read

List agents

Read only. Agents with direction, voice, languages, phone numbers and status (draft only, published, unpublished changes), plus used and total agent slots.

Scopesagents:read

Arguments

No arguments.

`get_agent`

Read

Get an agent

Read only. One agent's draft: config (basics, rules with goals, workflow), knowledge documents and the revision every edit tool needs. Live calls use the latest published version until the draft is published.

Scopesagents:read

Arguments

Field	Type	Description
`agentId`required	string (uuid)

`list_agent_versions`

Read

List agent versions

Read only. Published versions of an agent, newest first, with who published and the note. rollback_agent takes a version id from here.

Scopesagents:read

Arguments

Field	Type	Description
`agentId`required	string (uuid)

`list_voices`

Read

List voices

Read only. Voices an agent can use, with languages, gender and accent; kind is catalog or custom (this workspace's own ready voices). basics.voiceId takes an id from here.

Scopesagents:read

Arguments

No arguments.

`list_agent_templates`

Read

List agent templates

Read only. The templates a new agent can start from: key, name, description and direction. create_agent takes a key from here.

Scopesagents:read

Arguments

No arguments.

`list_custom_voices`

Read

List the workspace's own voices

Read only. The workspace's own voices with status (processing, ready, failed, disabled), the agents using each, and how many more it may have.

Scopesagents:read

Arguments

No arguments.

`create_agent`

Changes data

Create an agent

Changes data. Creates a new agent in the workspace from a template (list_agent_templates), as a draft: nothing is live or answers calls until publish_agent. Uses one of the workspace's free agent slots and is refused when none is left; it never buys a slot.

Scopesagents:write

Arguments

Field	Type	Description
`name`required	string
`templateKey`required	string

`update_agent_basics`

Draft only

Edit agent basics

Changes the draft only (live calls are unchanged until publish_agent). Replaces the agent's name and/or basics: voice, expressiveness (stability), speed, languages with their first message, call variables.

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`name`	string
`basics`	object
`basics.voiceId`required	string (uuid) \| null
`basics.stability`required	number
`basics.speed`required	number
`basics.languages`required	object[]
`basics.languages[].code`required	string
`basics.languages[].firstMessage`required	string
`basics.callVariables`required	object[]
`basics.callVariables[].name`required	string
`basics.callVariables[].example`required	string

`update_agent_rules`

Draft only

Edit agent rules

Changes the draft only. Replaces the agent's rules: purpose and tone, always/never say, transfers, end-call rules, data to capture, goals, call handling, voicemail message and additional instructions. Send the whole rules object from get_agent with your changes.

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`rules`required	object
`rules.purpose`required	string
`rules.tone`required	string
`rules.alwaysSay`required	string[]
`rules.neverSay`required	string[]
`rules.transfers`required	object[]
`rules.transfers[].to`required	"number"
`rules.transfers[].destination`required	string
`rules.transfers[].condition`required	string
`rules.transfers[].transferType`required	"conference" \| "blind"
`rules.transfers[].hours`required	string
`rules.transfers[].outsideHours`required	string
`rules.transfers[].callerMessage`required	string
`rules.transfers[].summary`required	string
`rules.transfers[].agentId`required	string (uuid)
`rules.endCallRules`required	string[]
`rules.dataToCapture`required	object[]
`rules.dataToCapture[].name`required	string
`rules.dataToCapture[].type`required	"string" \| "boolean" \| "integer" \| "number"
`rules.dataToCapture[].description`required	string
`rules.goals`required	object[]
`rules.goals[].name`required	string
`rules.goals[].description`required	string
`rules.goals[].value`	object
`rules.callHandling`required	object
`rules.callHandling.languageDetection`required	boolean
`rules.callHandling.voicemailDetection`required	boolean
`rules.callHandling.keypadTones`required	boolean
`rules.callHandling.skipTurn`required	boolean
`rules.voicemailMessage`required	string
`rules.additionalInstructions`required	string

`update_agent_goals`

Draft only

Edit agent goals

Changes the draft only. Replaces the agent's goals (rules.goals): what counts as a result of a call, each with "reached when" and an optional value to capture. Evaluated after every call.

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`goals`required	object[]
`goals[].name`required	string
`goals[].description`required	string
`goals[].value`	object
`goals[].value.type`required	"text" \| "number" \| "date" \| "yes_no"
`goals[].value.name`required	string
`goals[].value.unit`	string

`update_agent_workflow`

Draft only

Edit agent workflow

Changes the draft only. Replaces the agent's workflow (steps and the paths between them). Problems in the workflow are allowed in the draft but block publishing.

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`workflow`required	object
`workflow.steps`required	object[]
`workflow.steps[].kind`required	"start"
`workflow.steps[].id`required	string
`workflow.steps[].label`required	string
`workflow.steps[].position`required	object
`workflow.steps[].paths`required	object[]
`workflow.steps[].instructions`required	string
`workflow.steps[].collect`required	string[]
`workflow.steps[].documentIds`required	string (uuid)[]
`workflow.steps[].voiceId`required	string (uuid) \| null
`workflow.steps[].messages`required	object<string, string>
`workflow.steps[].action`required	"save_data"
`workflow.steps[].field`required	string \| ""
`workflow.steps[].destination`required	string \| ""
`workflow.steps[].transferType`required	"conference" \| "blind"
`workflow.steps[].agentId`required	string (uuid) \| null
`workflow.steps[].message`required	string

`attach_knowledge_document`

Draft only

Attach a knowledge document

Changes the draft only. Lets the agent use a knowledge base document (ids from list_knowledge_documents).

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`documentId`required	string (uuid)

`detach_knowledge_document`

Draft only

Detach a knowledge document

Changes the draft only. The agent stops using one of its own knowledge base documents once published; the document stays in the workspace. Company documents cannot be detached (remove them in Settings).

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`documentId`required	string (uuid)

`discard_agent_draft`

Draft only

Discard the agent draft

Changes data, cannot be undone. Throws away every unpublished change: the draft becomes the live version again.

Scopesagents:write

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.

`publish_agent`

Goes live

Publish an agent

Goes live. The draft becomes the next version and every new real call (inbound and campaigns) uses it at once. Needs a voice, a language with a first message and a workflow without problems. Confirm with the user first.

Scopesagents:publish

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`revision`required	integer	The agent's `revision` from get_agent. A stale one is refused: read the agent again.
`note`	string

`rollback_agent`

Goes live

Roll back an agent

Goes live. Publishes a copy of an earlier version (from list_agent_versions) as the next version; real calls use it at once. The draft is kept. Confirm with the user first.

Scopesagents:publish

Arguments

Field	Type	Description
`agentId`required	string (uuid)
`versionId`required	string (uuid)
`note`	string

`assign_phone_number_agent`

Goes live

Set the agent of a phone number

Goes live. The agent answers inbound calls on this number at once (agentId null: nobody answers). The agent needs a published version. Confirm with the user first.

Scopesagents:publish

Arguments

Field	Type	Description
`phoneNumberId`required	string (uuid)
`agentId`required	string (uuid) \| null

Knowledge base

`list_knowledge_documents`

Read

List knowledge documents

Read only. The workspace knowledge base: documents with status (processing, ready, failed) and size.

Scopesknowledge:read

Arguments

No arguments.

`add_knowledge_text`

Goes live

Add a text document

Changes data, also on live calls. Adds a text document to the knowledge base. Once processed it joins every agent, the published versions included.

Scopesknowledge:writeagents:publish

Arguments

Field	Type	Description
`name`required	string
`text`required	string

`add_knowledge_url`

Goes live

Add a web page

Changes data, also on live calls. Adds the content of one public web page (https) to the knowledge base. Once processed it joins every agent, the published versions included.

Scopesknowledge:writeagents:publish

Arguments

Field	Type	Description
`url`required	string (uri)

Phone numbers

`list_phone_numbers`

Read

List phone numbers

Read only. The workspace phone numbers with the agent that answers each one, open campaigns using it and inbound calls of the last 7 days.

Scopesnumbers:read

Arguments

No arguments.

Analytics

`get_analytics`

Read

Get analytics

Read only. Call results for a period in the workspace time zone: totals (calls, answer rate, goals reached, minutes, transfers, opt-outs) with the previous period (compare), calls over time, outcomes, call lengths, best hours to call, results by agent, campaign and number, and top captured values. custom needs from and to (local days). Set agent for one agent.

Scopesanalytics:read

Arguments

Field	Type	Description
`period`	"today" \| "yesterday" \| "7d" \| "30d" \| "90d" \| "this_month" \| "this_year" \| "custom" = "7d"
`from`	string (date)
`to`	string (date)
`direction`	"inbound" \| "outbound"
`agentId`	string (uuid)	Only this agent (the per-agent view)
`campaignId`	string (uuid)
`compare`	boolean = true	Also return the previous period

`get_goal_results`

Read

Get goal results

Read only. How often each goal was reached in a period: totals with the previous period's rate, by agent, campaign and number, over time, and captured values. Same period options as get_analytics; set agent for one agent.

Scopesanalytics:read

Arguments

Field	Type	Description
`period`	"today" \| "yesterday" \| "7d" \| "30d" \| "90d" \| "this_month" \| "this_year" \| "custom" = "7d"
`from`	string (date)
`to`	string (date)
`direction`	"inbound" \| "outbound"
`agentId`	string (uuid)	Only this agent (the per-agent view)
`campaignId`	string (uuid)
`compare`	boolean = true	Also return the previous period

Usage

`get_usage`

Read

Get minutes and usage

Read only. Minutes left and used in the current period.

Scopesusage:read

Arguments

No arguments.