Create a voice agent and lazily preserve the current workspace agent

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

POST

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

Authorization

BearerAuth
HTTP Bearer (JWT)
required

Path parameters

workspaceId
string
required

Request body JSON required

name
string
required
maxLength: 120 · minLength: 1
purpose
qualify_book
or
confirm
or
rehash
or
custom
required
idempotency_key
string
required
maxLength: 200 · minLength: 1

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

Create a voice agent and lazily preserve the current workspace agent

curl --request POST \
  --url 'https://api.channelautomation.com/api/workspaces/<workspaceId>/voice-ai/agents' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "string",
  "purpose": "qualify_book",
  "idempotency_key": "string"
}
'

const url = 'https://api.channelautomation.com/api/workspaces/<workspaceId>/voice-ai/agents';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json', Authorization: 'Bearer <token>'},
  body: JSON.stringify({name: 'string', purpose: 'qualify_book', idempotency_key: 'string'})
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));

import requests

url = "https://api.channelautomation.com/api/workspaces/<workspaceId>/voice-ai/agents"

payload = {
    "name": "string",
    "purpose": "qualify_book",
    "idempotency_key": "string"
}
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <token>"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Response example

{
  "success": true,
  "agent": {},
  "legacy": true,
  "uses_builtin": true,
  "agents": [
    {}
  ],
  "config": {}
}