Save only changed agent keys with revision compare and swap

Requires workspace owner, admin or manager. No page-load initialization. Creation requires capability version 1 from voice_service, ingest_worker and trigger.

PUT

https://api.channelautomation.com/api/workspaces/{workspaceId}/voice-ai/agents/{agentId}

Authorization

BearerAuth
HTTP Bearer (JWT)
required

Path parameters

workspaceId
string
required
agentId
string
required
format: uuid

Request body JSON required

revision
integer
required
minimum: 0
name
optional
string
maxLength: 120
instructions
optional
string
voice
optional
string
model
optional
string
outbound_voicemail_message
optional
string
Fixed AI queue voicemail drop message; empty means hang up without leaving a message
agent_enabled
optional
boolean
excluded_from_checklist
optional
boolean
lookup_http_auth_token
optional
string
lookup_builtin_api_key
optional
string
call_steps
optional
object
allowed_tools
optional
array of
string
structured_output_fields
optional
array of
object

Returns

200

Successful response with masked settings

JSON

success
optional
boolean
agent
optional
object
Profile metadata and name without voice_config or credentials
legacy
optional
boolean
True until profiles have been explicitly created
uses_builtin
optional
boolean
True when an OpenAI voice_ai block or profiles exist; controls the built-in fleet and tour
agents
optional
array of
object
Without profiles the latest legacy voice row is returned. A built-in config without a pointer returns a legacy entry with null agent_id that opens workspace settings without initialization.
config
optional
object
Normalized settings with credential configured booleans

400

Invalid request or unavailable agent

401

Authentication required

403

Workspace admin or manager required

404

Agent not found

409

Stale revision

500

Service error

503

Migration or consumer capabilities unavailable

curl --request PUT \ --url 'https://api.channelautomation.com/api/workspaces/<workspaceId>/voice-ai/agents/<agentId>' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data ' { "revision": 0, "name": "string", "instructions": "string", "voice": "string", "model": "string", "outbound_voicemail_message": "string", "agent_enabled": true, "excluded_from_checklist": true, "lookup_http_auth_token": "string", "lookup_builtin_api_key": "string", "call_steps": {}, "allowed_tools": [ "string" ], "structured_output_fields": [ {} ] } '