Agents

The editor tabs

In the console, an agent opens in an editor with one tab per area. Each tab maps to one part of the agent object.

Tab	Field in the agent object	Page
Agent	name, welcome_message, system_prompt	Agent tab
LLM	llm	LLM tab
Voice	voice	Voice tab
Transcriber	transcriber	Transcriber tab
Call	call	Call tab
Tools	tools	Tools
Analytics	analytics	Analytics tab
Webhook & number	webhook_url, phone_number	Webhook and number
Versions	(read only)	Versions

The agent object

{
  "id": "1b81a241c0e44f5c9d1f0e2a7c3b9d10",
  "name": "Front desk",
  "welcome_message": "Hello {customer_name}, thanks for calling City Clinic.",
  "system_prompt": "You are the receptionist of City Clinic. Help the caller book a visit.",
  "llm": {"provider": "gemini", "model": "gemini-3.5-flash-lite", "temperature": 0.4, "max_tokens": 300},
  "voice": {"provider": "cartesia", "model": "sonic-3.6", "voice_id": "", "voice_name": "", "language": "hi", "speed": 1.0},
  "transcriber": {"provider": "cartesia", "model": "ink-2", "turn_detection": "balanced", "language": "hi", "endpointing_ms": 300, "keyterms": []},
  "call": {
    "max_duration_seconds": 600,
    "hangup_after_silence_seconds": 15,
    "allow_interruptions": true,
    "interruption_min_words": 2,
    "call_start_hour": 9,
    "call_end_hour": 21,
    "timezone": "Asia/Kolkata",
    "record": true,
    "hangup_message": "",
    "hangup_on_prompt": false,
    "hangup_prompt": "You are deciding whether a phone conversation is complete. ...",
    "check_user_online": false,
    "user_online_message": "Are you still there?",
    "user_online_after_seconds": 9
  },
  "analytics": {"summarize": false, "extraction_prompt": ""},
  "tools": [],
  "webhook_url": "",
  "phone_number": "",
  "status": "active",
  "version": 1,
  "variables": ["customer_name"],
  "updated_by": "key:backend",
  "created_at": "2026-10-01T14:42:44.120000+05:30",
  "updated_at": "2026-10-01T14:42:44.120000+05:30"
}

Top-level fields

Field	Type	Default	Notes
id	string	generated	Read only.
name	string	required	1 to 120 characters.
welcome_message	string	""	See Agent tab.
system_prompt	string	""	See Agent tab.
llm	object	see LLM tab
voice	object	see Voice tab
transcriber	object	see Transcriber tab
call	object	see Call tab
analytics	object	see Analytics tab
tools	array	[]	See Tools.
webhook_url	string	""	See Webhook and number.
phone_number	string	""	See Webhook and number.
status	active or paused	active	A paused agent does not answer inbound calls on its number. Outbound calls are not affected.
version	integer	1	Read only. Goes up by one on every saved change.
variables	array of strings		Read only. Every {variable} the welcome message and prompt use, in order.
updated_by	string		Read only. The person, or key:<key name>, who saved the last change.
created_at, updated_at	ISO 8601		Read only, UTC.

Endpoints

Action	Request	Permission
List agents	GET /api/v1/agents	agents.view
Create an agent	POST /api/v1/agents	agents.edit
Get one agent	GET /api/v1/agents/{id}	agents.view
Replace an agent	PUT /api/v1/agents/{id}	agents.edit
Duplicate an agent	POST /api/v1/agents/{id}/duplicate	agents.edit
Delete an agent	DELETE /api/v1/agents/{id}	agents.edit
Versions	GET /api/v1/agents/{id}/versions and more	see Versions
Place a call	POST /api/v1/agents/{id}/call	calls.place

The full schemas are in the API reference.

Create

POST /api/v1/agents takes the agent’s configuration (every field in the table above except the read-only ones). Missing fields get their defaults. It returns 201 with the agent.

curl -X POST https://voxa.abhinavyadav.in/api/v1/agents \
  -H "X-API-Key: $VOXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Front desk", "system_prompt": "You are the receptionist of City Clinic."}'

Update

PUT /api/v1/agents/{id} replaces the whole configuration. A field you leave out goes back to its default, so read the agent first, change what you need, and send it all back:

curl -s https://voxa.abhinavyadav.in/api/v1/agents/$AGENT_ID -H "X-API-Key: $VOXA_API_KEY" > agent.json
# edit agent.json
curl -X PUT https://voxa.abhinavyadav.in/api/v1/agents/$AGENT_ID \
  -H "X-API-Key: $VOXA_API_KEY" \
  -H "Content-Type: application/json" \
  -d @agent.json

Read-only fields in the body (id, version, variables and so on) are ignored. A PUT that changes nothing returns the agent as it is and does not create a version.

Changes apply to calls that start after the save. A call already in progress keeps the configuration it started with.

Duplicate and delete

POST /api/v1/agents/{id}/duplicate creates a copy named <name> (copy), without the phone number. DELETE /api/v1/agents/{id} returns 204 and removes the agent and its versions. Queued calls for a deleted agent are canceled when the queue reaches them; past calls keep their records.

Errors

Status	When
404	The agent is not in your workspace.
409	Your plan’s agent limit is reached (your plan allows 10 agents: ...), or the phone number belongs to another workspace.
422	A field is out of range, a tool is invalid, or the agent uses a provider your workspace may not use (Deepgram is not available to this workspace).

GET /api/v1/providers lists every provider and whether your workspace may use it.