Agents

Manage AI voice agents with custom STT, LLM, and TTS configurations.

Endpoints

Method	Endpoint	Description
GET	`/agents`	List all agents
POST	`/agents`	Create a new agent
GET	`/agents/{id}`	Get an agent
PATCH	`/agents/{id}`	Update an agent
DELETE	`/agents/{id}`	Delete an agent

List All Agents

Retrieve all AI voice agents in your account.

GET /agents

Request

Response

{
  "agents": [
    {
      "id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
      "name": "Customer Support Agent",
      "business_name": "Acme Corp",
      "is_active": true,
      "first_message": "Hallo, welkom bij Acme. Waarmee kan ik u helpen?",
      "voicemail_detection": false,
      "max_duration_seconds": 600,
      "autonomous_silence_handling": true,
      "stt_config": {
        "provider": "deepgram",
        "model": "nova-3-general",
        "language": "nl",
        "keyterms": ["ja", "nee", "oké"]
      },
      "llm_config": {
        "provider": "openai",
        "model": "gpt-4o-mini",
        "temperature": 0.7,
        "messages": [...]
      },
      "tts_config": {
        "provider": "openai",
        "voice_id": "alloy",
        "language": "nl"
      },
      "created_at": "2025-12-13T10:00:00.000Z",
      "updated_at": "2025-12-13T10:00:00.000Z"
    }
  ]
}

Create a New Agent

Create a new AI voice agent. Only name is required.

POST /agents

Request Body

Field	Type	Required	Description
`name`	string	Yes	Agent display name
`business_name`	string	No	Business the agent represents
`notification_email`	email	No	Email for call notifications
`first_message`	string	No	Initial greeting message
`is_active`	boolean	No	Whether agent is active (default: true)
`voicemail_detection`	boolean	No	Enable voicemail detection
`voicemail_message`	string	No	Message to leave on voicemail
`max_duration_seconds`	integer	No	Maximum call duration in seconds
`autonomous_silence_handling`	boolean	No	Auto-handle caller silence
`webhook_url`	URL	No	Webhook URL for call events
`webhook_secret`	string	No	Secret for webhook signatures
`webhook_events`	array	No	Events to send to webhook
`stt_config`	object	No	Speech-to-text configuration
`llm_config`	object	No	Language model configuration
`tts_config`	object	No	Text-to-speech configuration
`analysis_plan`	object	No	Post-call analysis configuration

Example Request

Response (201 Created)

{
  "agent": {
    "id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "name": "Customer Support Agent",
    "business_name": "Acme Corp",
    "is_active": true,
    "voicemail_detection": true,
    "max_duration_seconds": 600,
    "autonomous_silence_handling": true,
    "created_at": "2025-12-13T10:00:00.000Z",
    "updated_at": "2025-12-13T10:00:00.000Z"
  }
}

Get an Agent

Retrieve a specific agent by ID.

GET /agents/{id}

Parameters

Name	In	Type	Description
`id`	path	UUID	Agent UUID

Request

Response

{
  "agent": {
    "id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "name": "Customer Support Agent",
    "business_name": "Acme Corp",
    "is_active": true,
    "stt_config": { ... },
    "llm_config": { ... },
    "tts_config": { ... }
  }
}

Update an Agent

Update an existing agent. Only provided fields will be updated.

PATCH /agents/{id}

Parameters

Name	In	Type	Description
`id`	path	UUID	Agent UUID

Request Body

All fields are optional. Only include fields you want to update.

Example Request

Response

{
  "agent": {
    "id": "17a0cb75-fa09-4bdd-9a44-92a70d829c88",
    "first_message": "Goedemiddag, u spreekt met Acme support.",
    "is_active": false,
    "max_duration_seconds": 900,
    "updated_at": "2025-12-13T11:30:00.000Z"
  }
}

Delete an Agent

Delete an agent. Any phone numbers assigned to this agent will be unlinked.

DELETE /agents/{id}

Parameters

Name	In	Type	Description
`id`	path	UUID	Agent UUID

Request

Response

{
  "success": true
}

Configuration Schemas

STTConfig

Speech-to-text configuration.

Field	Type	Required	Description
`provider`	string	Yes	`deepgram`
`model`	string	Yes	e.g., `nova-3-general`
`language`	string	Yes	e.g., `nl`, `en`, `de`
`keyterms`	array	No	Words to boost recognition accuracy

LLMConfig

Language model configuration.

Field	Type	Required	Description
`provider`	string	Yes	`openai`, `anthropic`, `groq`, `mistral`, `xai`, `xai_realtime`
`model`	string	Yes	e.g., `gpt-4o-mini`, `claude-sonnet-4`, `grok-4-1-fast-non-reasoning`
`temperature`	number	No	0-2, default 0.7
`messages`	array	No	System prompts with role/content
`tools`	array	No	Available function tools

Note: The xai provider uses Grok text models and shares the same API key (xai_secret_id) as xai_realtime. Unlike xai_realtime (speech-to-speech), the xai provider is a standard text LLM and requires separate STT and TTS configuration.

xAI Text Models:

Model	Pricing (Input/Output per 1M tokens)	Context
`grok-4-1-fast-non-reasoning`	$0.20/$ 0.50	2M
`grok-4-1-fast-reasoning`	$0.20/$ 0.50	2M
`grok-4-fast-non-reasoning`	$0.20/$ 0.50	2M
`grok-4-fast-reasoning`	$0.20/$ 0.50	2M
`grok-code-fast-1`	$0.20/$ 1.50	256K
`grok-4-0709`	$3.00/$ 15.00	256K
`grok-3-mini`	$0.30/$ 0.50	131K
`grok-3`	$3.00/$ 15.00	131K

TTSConfig

Text-to-speech configuration.

Field	Type	Required	Description
`provider`	string	Yes	`openai`, `elevenlabs`, `cartesia`, `local`
`voice_id`	string	Yes	Voice identifier
`language`	string	Yes	e.g., `nl`, `en`
`model`	string	No	Model name (provider-specific)
`speed`	number	No	Speech speed (ElevenLabs: 0.5-2.0)
`stability`	number	No	Voice stability (ElevenLabs: 0-1)
`similarity_boost`	number	No	Clarity boost (ElevenLabs: 0-1)
`use_speaker_boost`	boolean	No	Speaker boost (ElevenLabs)

ElevenLabs TTS Models:

Model	Description
`eleven_flash_v2_5`	Fastest, low-latency (default)
`eleven_v3`	Expressive dialogue with audio tag support (see below)
`eleven_multilingual_v2`	Best quality, multilingual
`eleven_turbo_v2_5`	Balanced speed and quality
`eleven_monolingual_v1`	English only

Eleven v3 Audio Tags: When using the eleven_v3 model, the LLM output can include audio tags in square brackets to control emotional delivery. For example: [sad], [laughing], [whispering], [cheerfully], [cautiously]. Structure your system prompt to instruct the LLM to insert these cues. Example: [professional] Let me look that up for you.

Provider Notes:

local provider is cost-efficient and uses robotic voices that improve user engagement for transactional calls

elevenlabs provides natural human-like voices with advanced controls

openai offers good quality with simple configuration

AnalysisPlan

Post-call analysis configuration.

Field	Type	Required	Description
`structured_data_plan`	object	No	JSON schema for structured extraction
`min_messages_threshold`	integer	No	Minimum messages before analysis runs

See Agent Schema for complete details.

Endpoints#

List All Agents#

Request#

Response#

Create a New Agent#

Request Body#

Example Request#

Response (201 Created)#

Get an Agent#

Parameters#

Request#

Response#

Update an Agent#

Parameters#

Request Body#

Example Request#

Response#

Delete an Agent#

Parameters#

Request#

Response#

Configuration Schemas#

STTConfig#

LLMConfig#

TTSConfig#

AnalysisPlan#

Endpoints

List All Agents

Request

Response

Create a New Agent

Request Body

Example Request

Response (201 Created)

Get an Agent

Parameters

Request

Response

Update an Agent

Parameters

Request Body

Example Request

Response

Delete an Agent

Parameters

Request

Response

Configuration Schemas

STTConfig

LLMConfig

TTSConfig

AnalysisPlan