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. nodes is the conversation-flow graph; subflow_ref nodes are embedded as snapshots at publish time.

flowName*

string

startNodeId*

string

nodes*

FlowNode[]

globalSettings

object

voiceEngine*

'poc' | 'retell'

voiceId

string

ttsBackend

'kokoro' | 'elevenlabs' | 'cartesia' | 'minimax'

Returns { version, flow }

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

variables

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

Returns { agentId, versionId, versionNumber, template, voiceEngine, retellAgentId?, warnings? }

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 phone numbers

Returns { phoneNumbers }

Route a number to an agent version

direction*

'inbound' | 'outbound'

agentVersionId

string | null

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

?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).

Returns { callLog }

Stream a call recording

Returns audio

List batch calls

Returns { batches }

Create a batch

agentVersionId*

string

phoneNumbers*

string[] (E.164)

Returns { batch }

Start a batch

Dials paced by the platform-wide and per-workspace rate limits.

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 }

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 }