Agents

Create and manage voice agents over the API.

Everything the agent builder does is available here. The API manages the core, portable fields of an agent; console-only settings (multi-prompt flows, announcement config) are preserved untouched when you update.

Agent shapes:

  • List (publicAgent): { id, name, voice, language, status }
  • Detail / write (publicAgentManaged): the list fields plus systemPrompt, workflowTemplate, vertical, policyRef, allowedTransferNumbers, extractionSchema, knowledgeBaseId, toolIds.

List agents

GET /v1/agents  ·  scope agents:read

{ "data": [ { "id": "agt_…", "name": "Sales", "voice": "simran", "language": "hi", "status": "active" } ] }

Returns every agent in the workspace.

Get an agent

GET /v1/agents/:id  ·  scope agents:read → { "data": publicAgentManaged }. Unknown id → 404 agent not found.

Create an agent

POST /v1/agents  ·  scope agents:write

New agents are created as status: "draft" - publish before running them.

Body

Field Type Required Default / constraints
name string yes 1–120 chars
systemPrompt string no max 16000, default ""
voice string no max 80, default ""
language enum no en, hi, bn, gu, kn, ml, mr, or, pa, ta, te - default en
workflowTemplate enum no collections, onboarding, prompt-driven - default prompt-driven
vertical enum no general, collections, lending, financial_services, debt_recovery - default general
policyRef string no compliance-pack ref (1–120), default generic-safe@1. Built-in (e.g. india-lending@1) or custom (cpk_…)
toolIds string[] no catalog tool ids (each 1–64, max 50), default []
allowedTransferNumbers string[] no warm-transfer allowlist (each 1–20, max 50), default []
extractionSchema array no fields to capture: { key, label, type: "text"|"boolean"|"number" } (max 50), default []
knowledgeBaseId string | null no default null

Validation

  • A regulated vertical (lending, financial services, debt recovery, collections) must be paired with a valid workflowTemplate and a compliance pack that resolves - a regulated vertical requires a DLT pack, or you get a 400/422.
  • allowedTransferNumbers and policyRef are validated.

Response - 201

{ "data": publicAgentManaged } with status: "draft".

Replace an agent

PUT /v1/agents/:id  ·  scope agents:write

Replaces the managed fields (same body as create). Console-only settings - multi-prompt flow, call context, variants - are preserved, so an API update never wipes a flow built in the console. Same validation as create. Unknown id → 404.

Response 200: { "data": publicAgentManaged }.

Publish or unpublish

POST /v1/agents/:id/status  ·  scope agents:write

{ "status": "active" }   // publish;  "draft" to unpublish

Publishing re-checks the vertical guard and compliance pack against the saved config (it can fail with the same guard errors). Response 200: { "data": publicAgentManaged }.

Delete an agent

DELETE /v1/agents/:id  ·  scope agents:write → { "data": { "id": "agt_…", "deleted": true } }.

  • 409 agent is attached to a campaign - detach it first
  • 404 agent not found

Next: Contacts →