Agents

Verified against backend/internal/publicapi/dto.go, builder_dto.go, agents_handler.go, agents_write_handler.go, and routes.go.

The internal agent model has roughly 50 tunable fields — VAD thresholds, noise profiles, interrupt behavior, silence timeouts. None of those are exposed here on purpose: this surface covers what's needed to stand up a working voice agent and answer a call. Widening it later is easy; narrowing a public field once someone's SDK depends on it is a breaking change.

List / get

curl https://api.voicematrix.ai/api/v1/ext/agents -H "X-API-Key: vm_live_..."

List/get response (read surface):

{ "id": "...", "name": "Support Agent", "phone_number": "+97233822555", "language": "he", "is_active": true, "status": "published", "created_at": "..." }

Create an agent

curl -X POST https://api.voicematrix.ai/api/v1/ext/agents \
  -H "X-API-Key: vm_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "prompt": "You are a helpful support agent for Acme Ltd...",
    "greeting": "שלום! איך אפשר לעזור?",
    "language": "he",
    "voice": "azure-neural-hila"
  }'

A new agent is created unpublished. Going live is a separate, explicit step — see Publish below.

Update an agent

PATCH /agents/:id

Every field on the create request is here too, but as a pointer/optional field — genuinely optional, not "send empty string to clear." Sending greeting absent from the JSON body leaves the existing greeting untouched; there is a distinct representation for "clear this field" versus "I didn't mention this field." Also accepts a webhook object — this is the synchronous call-enrichment hook fired while a caller is connecting (a lookup against your CRM), which is a different thing from the outbound event webhooks described in Webhooks.

Responses from the write surface include a version field — an optimistic-concurrency token. Send it back as an If-Match header on your next PATCH and the update is rejected with 409 if someone (or something) else wrote to the agent first.

Publish / unpublish

curl -X POST https://api.voicematrix.ai/api/v1/ext/agents/<id>/publish -H "X-API-Key: vm_live_..."

{ "id": "...", "status": "published", "published": true, "warning": "Publishing gates the widget, share-link, SMS and public-API surfaces. It does NOT stop or start inbound phone calls — inbound routing is controlled by the phone number binding, independent of publish status." }

Read that warning literally: unpublishing an agent does not stop it from answering its bound phone line. Inbound PSTN routing resolves the agent directly from the phone number's binding and does not check publish status. If you need a number to stop ringing an agent, unbind the number (see Phone Numbers) — don't rely on unpublish for that.

Next

• Knowledge Base — attach documents to an agent
• Phone Numbers — bind a number so the agent actually answers calls
• Voice & Agent Capabilities — voices, models, multi-agent handoff