Build on CallDeskTech.

Who am I?

For an API key, returns the tenant it is pinned to — use that id in the paths below.

Returns { auth, tenantId, tenantName }

List agents

Each agent includes its latest version’s engine/voice and any routed phone numbers.

Returns { agents: Agent[] }

Create an agent

name*

string

mode

'simple' | 'advanced'

Returns { agent }

Get an agent

Returns { agent }

Rename an agent

name

string

Returns { agent }

Delete an agent

Also deletes its versions, subflows and knowledge bases.

Returns { success }

List versions

Returns { versions: AgentVersion[] }

Publish a new version

Versions are immutable. Set globalSettings.language (en default; es, fr, pt-BR, it, nl, hi, de, pl, id, ar) for a non-English agent: the engine switches speech recognition, the reply language and the voice, and a non-English poc agent is pinned to the ElevenLabs voice (billed at the ElevenLabs rate). nodes is the conversation-flow graph; subflow_ref nodes are embedded as snapshots at publish time. The response may include a non-blocking warnings array of { code, message }: booking_without_calendar means the flow collects appointments but the workspace has no calendar connected (or globalSettings.calendarTools is false), so the agent takes a request instead of booking. The version is still published. Set requireBookingTools: true to make that case an error instead: the request is refused with HTTP 422 and code booking_requires_calendar (plus reasons and fix) before anything is saved or billed. When the flow has no booking intent, or a calendar is connected, the flag changes nothing.

flowName*

string

startNodeId*

string

nodes*

FlowNode[]

globalSettings

object

requireBookingTools

boolean (optional, default false; true refuses the publish with 422 code booking_requires_calendar when the flow collects appointments but no calendar is connected or globalSettings.calendarTools is false; nothing is saved or billed)

voiceEngine*

'poc' | 'retell'

voiceId

string

tier

'lite' | 'standard' | 'pro' (optional; poc engine only; see GET /pricing; 'lite' also needs acceptLowerQuality: true, to confirm you are choosing its efficient, lower-cost voice; the tier picks the language model and voice for you; omit to keep the flat per-minute price of the voice backend)

routingMode

'expert_backup' (optional; Expert backup: hands the hard turns to a stronger model for better accuracy on hard turns; 1.5 cents per minute extra while on; poc engine with tier lite or standard only, not pro; needs acceptExpertBackup: true; omit for standard routing)

acceptExpertBackup

boolean (required true with routingMode expert_backup; without it you get 400 code expert_backup_acceptance_required with the terms)

ttsBackend

'kokoro' | 'elevenlabs' | 'cartesia' | 'minimax' | 'piper' (advanced)

llmModel

string (advanced, optional; poc engine only; overrides the tier; see GET /models; default claude-haiku-4-5-20251001)

ttsModel

string (advanced, optional; elevenlabs or cartesia only; overrides the tier; see GET /models)

Returns { version, flow, warnings?: { code, message }[] }. 422 { error, code: "booking_requires_calendar", reasons: string[], fix } when requireBookingTools is true and the agent cannot book

List pricing tiers

The pricing tiers (Lite, Standard, Pro) and planned optional add-ons (coming soon, not purchasable yet), with price per minute, the engine behind each tier (ratings for voice, response speed and reasoning), what every plan includes, and the phone number extra. Every tier is bring-your-own carrier. No authentication needed. Pass a tier id as tier when publishing a version. Lite is coming_soon and cannot be selected yet. Agents published without a tier keep the flat per-minute price of their voice backend. On every plan you can also buy a phone number from us as a paid extra (premium Twilio carrier: $2.00 per month per number plus 1.5 cents per minute of inbound calls; Telnyx carrier: $1.00 per month plus 1 cent per minute of inbound calls; outbound uses your own carrier); bringing your own number or carrier is free. The response also lists the expert backup extra (expertBackup: price, tiers, terms). Add-ons cannot be bought yet; their amounts are null until they launch.

Returns { currency, unit, tiers: { id, name, pricePerMinuteCents, pricePerMinuteDollars, tagline, whoItsFor, ratings: { voice, responseSpeed, reasoning }, carrierMode: 'byo' | 'managed', availability: 'live' | 'coming_soon' }[], addOns: { id, label, description, centsPerMinute | null, proposed, defaultOn }[], includedOnAllTiers, carrierNote, notes, phoneNumbers, expertBackup: { id, label, description, availability, tiers, centsPerMinute, publishFields, terms } }

List model options

The language models (llmModel) and voice models (ttsModel) you can choose when publishing a version, each with a tested or preview status and notes on speed and reliability. If the voice engine cannot use the chosen model, or the provider fails before the agent speaks, the default model answers, so a call never fails because of this setting. A flow node can override the language model with params.model.

Returns { defaults: { llmModel }, llmModels: { id, label, provider, default?, status, notes }[], ttsModels: { id, backend, label, default?, notes }[], notes: string[] }

List agent templates

Built-in templates (receptionist, medical receptionist, payment collection, IVR navigation and more) that can be installed as an agent.

Returns { templates: { id, label, description, category, defaultVariables: {name: value}, variables: string[] (the {{placeholders}} you can set on install) }[] }

Create an agent from a template

Creates the agent, its subflows and knowledge base, and publishes version 1. voiceEngine "poc" runs on CallDesk; "retell" also creates the equivalent Retell conversation-flow agent (some node types are approximated; see warnings). transferTo and functionUrl fill empty transfer numbers and function webhooks. variables sets the template's {{placeholders}} (see GET /agent-templates); business_name defaults to the tenant name.

templateId*

string (from GET /agent-templates)

name

string

voiceEngine

'poc' | 'retell'

transferTo

E.164 string

functionUrl

https URL

calendarTools

false to turn off live calendar lookups and bookings

language

agent language: 'en' (default), 'es', 'fr', 'pt-BR', 'it', 'nl', 'hi', 'de', 'pl', 'id' or 'ar'

variables

object, e.g. {"business_name": "Acme Dental", "agent_name": "Sam"}

Returns { agentId, versionId, versionNumber, template, voiceEngine, retellAgentId?, warnings? (Retell conversion notes, string[]), publishWarnings?: { code, message }[] (e.g. booking_without_calendar) }

List an agent's environments

Every agent has "staging" and "production", each pointing at the version it currently runs (null if nothing has been promoted into it yet).

Returns { environments: { id, name, version_id, updated_at }[] }

Promote a version into staging or production

Every phone number (or batch call) routed to this environment picks up the new version immediately — no need to re-route. Rolling back is promoting an older version again.

versionId*

string

Returns { environment, resynced }

List subflows

?agentId Only library subflows plus this agent’s own

Returns { subflows: Subflow[] }

Create a subflow

name*

string

scope

'agent' | 'library'

agentId

string (agent scope)

nodes

FlowNode[]

startNodeId

string

Returns { subflow }

Get a subflow

Returns { subflow }

Update a subflow

Already-published versions keep the snapshot they embedded.

name

string

nodes

FlowNode[]

startNodeId

string

scope

string

Returns { subflow }

Delete a subflow

Returns { ok }

List knowledge bases

Returns { knowledgeBases }

Create a knowledge base

Set agent_id — a knowledge_base node only sees content from a KB attached to its agent.

name*

string

source_type*

'website' | 'pdf' | 'manual'

source_url

string

agent_id

string

Returns { knowledgeBase }

Rename or re-attach to an agent

name

string

agent_id

string | null

Returns { knowledgeBase }

Delete a knowledge base

Returns { success }

List Q&A items

Returns { items }

Add Q&A items

items*

{ question: string, answer: string }[]

Returns { items }

List jingle and sound effects

Returns the workspace's jingle and sound effects (asset_type is jingle or sound_effect); enabled: false rows are ones that were replaced.

Returns { assets }

Generate a jingle or sound effect

Generates the sound from a text description, then stores it. Spends generation credits. A workspace has one jingle and up to 10 sound effects; a new jingle replaces the current one, and reusing a sound effect name replaces that effect. durationSec is 1-12. A sound effect needs a description saying WHEN the agent should play it: the agent reads it. Only plays on agents running the in-house engine; Retell agents are unaffected. Can take up to a minute.

type*

'jingle' | 'sound_effect'

name*

string (letters, numbers, _ and -)

description

string (required for sound_effect)

prompt*

string (what the sound should be, max 500 chars)

durationSec*

number (1-12)

Returns { asset }

Delete a jingle or sound effect

Callers stop hearing it immediately.

Returns { ok }

Preview a sound

Returns a playable WAV (audio/wav) of exactly what callers hear.

Returns audio/wav

List phone numbers

Returns { phoneNumbers }

Buy a phone number

On every plan this is a paid extra. Choose the carrier: twilio (premium) is $2.00 per month per number plus 1.5 cents per minute of inbound calls to your purchased numbers; telnyx is $1.00 per month plus 1 cent per minute of inbound calls; outbound calling uses your own carrier. Pass acceptNumberAddOn: true to accept the terms (without it you get 400 code number_addon_acceptance_required with the terms). Billing is set up before the number is bought and undone if the purchase fails. Bringing your own number is free. Requires a payment method on file.

areaCode

string (optional)

carrier

'twilio' (default) | 'telnyx'

acceptNumberAddOn

boolean

Returns { phoneNumber }

Release a phone number

Removes the number from your workspace. A number bought from us is released on its carrier first, and its monthly charge drops by one number (the charges end when you hold none). A number you registered yourself is only unregistered.

Returns { deleted: true }

Route a number to an agent version or environment

Pass exactly one of agentVersionId (a specific version, direct pin) or environmentId (staging/production — the number always runs whatever version that environment currently points to, so promoting later needs no further call here).

direction*

'inbound' | 'outbound'

agentVersionId

string | null

environmentId

string

Returns { phoneNumber }

Place an outbound call

Calls toNumber from this number using its outbound agent. Rate-limited per workspace (429).

toNumber*

E.164 string

Returns { call: { sid, to } }

List calls

Each call includes analysis.issues (problems found automatically after the call; see Get a call).

?limit default 50

Returns { callLogs: CallLog[] }

Get a call

Includes transcript, outcome, duration, transfer status, and analysis (post-call analysis fields, null unless configured on the agent). analysis.issues lists problems found automatically after the call, each { code, severity: 'high'|'medium'|'low', message, evidence: string[], fix }; codes: claimed_booking_without_tool, placeholder_read_aloud, number_readback_mismatch, no_fields_collected, long_silence. The key is absent until the call has been checked and [] when nothing was found. Blocked and internal-test calls are never checked.

Returns { callLog }

Stream a call recording

Returns audio

List batch calls

Returns { batches }

Create a batch

phoneNumbers accepts either a plain list (newline/comma/semicolon-separated) or a CSV with a header row — a column named phone/phone_number/to/to_number/number is the recipient, every other column becomes a per-call dynamic variable (e.g. a "first_name" column lets the agent say {{first_name}}). Omit scheduledAt to leave the batch pending for a manual/API "run" call now; set it to a future ISO timestamp to have the platform run it automatically at that time instead.

agentVersionId*

string

phoneNumbers*

string (plain list) or CSV text with a phone/phone_number/to/to_number/number column plus optional variable columns

name

string, optional label

scheduledAt

ISO datetime, optional — future time to run automatically instead of on manual/API trigger

callTimeWindow

optional { timezone: IANA string, days: number[] (0=Sun..6=Sat), start_hour: 0-23, end_hour: 1-24 } — restricts when this batch is allowed to dial

Returns { batch }

Get a batch and its targets

Each target includes its phone number, dial status, dynamic_variables used, and call_log_id once placed.

Returns { batchCall, targets }

Start a batch

Dials paced by the platform-wide and per-workspace rate limits. Returns 409 if the batch is scheduled for later and not yet due, or outside its callTimeWindow — retry after that time.

Returns { started, ... }

List webhooks

Returns { webhooks }

Register a webhook

Events: call.started (Retell-engine calls only), call.completed (includes analysis when configured), call.transferred, call.analyzed (post-call analysis results). Deliveries are signed with the returned whsec_ secret (X-CallDesk-Event header names the event).

url*

https URL

events

('call.started' | 'call.completed' | 'call.transferred' | 'call.analyzed')[]

Returns { webhook }

Update a webhook

url

string

events

string[]

enabled

boolean

Returns { webhook }

Delete a webhook

Returns { success }

Send a test delivery

Returns { ok }

List contacts

Returns { contacts }

List CRM connections

Access/refresh tokens are never returned — write-only, like API keys.

Returns { connections: { id, provider, provider_account_id, expires_at, created_at }[] }

Disconnect a CRM

?provider 'hubspot' | 'salesforce'

Returns { success }

Start HubSpot OAuth connect

Browser-navigation endpoint (not JSON) — 302s to HubSpot's authorize screen. Owner/admin only.

Returns 302 redirect

Look up a caller in HubSpot (CRM→us)

On-demand lookup by phone for call-time personalization, e.g. injecting {{crm_company_name}} as a dynamic variable. No background sync.

?phone E.164 phone number

Returns { variables: { crm_contact_found, crm_first_name?, crm_last_name?, crm_company_name?, crm_email?, crm_job_title? } }

Call analytics by day

?days 7 | 30 | 90

Returns { series, totals }

QA scores, resolution and transfer metrics

?days 7 | 30 | 90

Returns { avgScore, resolutionRate, transferSuccessRate, ... }

List simulation test cases

Returns { testCases }

Create a test case

name

string

persona

string

successCriteria

string

Returns { testCase }

Run a simulation

Returns { passed, transcript, reasoning }

List Copilot suggestions

Returns { suggestions }

Analyze recent calls for flow-edit suggestions

Looks at this agent's recent real calls (transcripts + QA critiques, whichever number is currently routed to it) for recurring problems and proposes concrete node-level prompt edits, each grounded in specific call transcripts. Requires at least 5 usable calls, otherwise returns a not_enough_history status instead of guessing. Never writes to the flow — suggestions are persisted as pending and must be accepted or dismissed via the suggestions route.

Returns { status, callCount, summary, suggestions: { id, node_id, current_text, suggested_text, rationale, supporting_call_ids, status }[] }