Agents

GET /v1/agents#

List agents. Returns all agents on your account. If your operator has configured guardrails, the expanded agent carries them read-only, and guardrails.input.action_by_channel says what the input guard's action means on each channel **for this agent**. It matters for one value: escalate is a real handover to a person only in a **chat** on an agent whose web_widget.enabled and web_widget.takeover.enabled are both on, because the handover runs through the same path the request-a-human tool uses and that path refuses when either switch is off. On a **voice** call it is refuse plus the fallback line and nothing more, since a phone leg has no takeover queue to enter. So one stored escalate reads back as {"voice": "refuse", "chat": "escalate"} on an agent with the widget handover armed and as {"voice": "refuse", "chat": "refuse"} on one without it - neither is a misconfiguration, they are the same setting reported honestly for the agent you asked about. The field is filled by the server on reads and ignored on writes.

Responses

Example request

curl "https://api.voiceland.ai/v1/agents" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "deploy_state": "deployed",
      "name": "front-desk"
    }
  ]
}

POST /v1/agents#

Create or update an agent. Upserts an agent from the narrow tenant shape. Server-managed knobs (model, transcriber tuning, durations, tools) are filled from your account defaults; the response returns the fully expanded agent so you can see what was applied. Unknown fields are rejected with 422. If your operator has configured guardrails, the expanded agent carries them read-only, and guardrails.input.action_by_channel says what the input guard's action means on each channel **for this agent**. It matters for one value: escalate is a real handover to a person only in a **chat** on an agent whose web_widget.enabled and web_widget.takeover.enabled are both on, because the handover runs through the same path the request-a-human tool uses and that path refuses when either switch is off. On a **voice** call it is refuse plus the fallback line and nothing more, since a phone leg has no takeover queue to enter. So one stored escalate reads back as {"voice": "refuse", "chat": "escalate"} on an agent with the widget handover armed and as {"voice": "refuse", "chat": "refuse"} on one without it - neither is a misconfiguration, they are the same setting reported honestly for the agent you asked about. The field is filled by the server on reads and ignored on writes.

Request body

application/json Schema: Agent

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "identity": {
    "initial_message": "Acme Clinic, how can I help?",
    "system_prompt": "You are the front desk of Acme Clinic. Help callers book appointments."
  },
  "language": {
    "primary": "en-US"
  },
  "name": "front-desk",
  "record_call": true,
  "voice": {
    "provider": "voiceland",
    "voice_id": "pNInz6obpgDQGcFmaJgB"
  }
}'

Example response

{
  "api_version": "2026-04-26",
  "deploy_state": "draft",
  "name": "front-desk"
}

POST /v1/agents/generate#

Generate an agent from a brief. Uses the language model to draft a complete agent from a free-text description, then upserts it. Returns the expanded agent.

Request body

application/json Schema: AgentGenerateRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/generate" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "description": "A friendly receptionist that greets callers and answers general questions about the business.",
  "language": "en-US",
  "name": "greeter",
  "record_call": true
}'

Example response

{
  "deploy_state": "draft",
  "name": "clinic-bot"
}

POST /v1/agents/wizard#

Draft an agent from structured input. Builds an agent from a small set of structured fields (industry, language, voice persona, transfer behavior). Non-persisting, returns the draft yaml + tenant agent for review.

Request body

application/json

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/wizard" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "industry": "receptionist",
  "language": "en-US",
  "name": "front-desk",
  "voice": {
    "gender": "female",
    "style": "warm"
  }
}'

Example response

{
  "name": "front-desk",
  "warnings": [],
  "yaml": "name: front-desk\n…"
}

DELETE /v1/agents/{name}#

Delete an agent. Permanently deletes the agent.

Parameters

Responses

Example request

curl -X DELETE "https://api.voiceland.ai/v1/agents/{name}" \
  -H "Authorization: Bearer VL_API_KEY"

GET /v1/agents/{name}#

Get an agent. Returns the fully expanded agent spec, including the server-filled defaults. If your operator has configured guardrails, the expanded agent carries them read-only, and guardrails.input.action_by_channel says what the input guard's action means on each channel **for this agent**. It matters for one value: escalate is a real handover to a person only in a **chat** on an agent whose web_widget.enabled and web_widget.takeover.enabled are both on, because the handover runs through the same path the request-a-human tool uses and that path refuses when either switch is off. On a **voice** call it is refuse plus the fallback line and nothing more, since a phone leg has no takeover queue to enter. So one stored escalate reads back as {"voice": "refuse", "chat": "escalate"} on an agent with the widget handover armed and as {"voice": "refuse", "chat": "refuse"} on one without it - neither is a misconfiguration, they are the same setting reported honestly for the agent you asked about. The field is filled by the server on reads and ignored on writes.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "deploy_state": "deployed",
  "name": "front-desk",
  "spec": {
    "guardrails": {
      "input": {
        "action": "escalate",
        "action_by_channel": {
          "chat": "escalate",
          "voice": "refuse"
        },
        "enabled": true
      }
    }
  }
}

POST /v1/agents/{name}/deploy#

Deploy an agent. Publishes the agent so it answers/originates live calls.

Parameters

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/deploy" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "deploy_state": "deployed",
  "name": "front-desk"
}

POST /v1/agents/{name}/rollback#

Roll back an agent. Restores a prior version as the current spec.

Parameters

Request body

application/json Schema: RollbackRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/rollback" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "version_id": "v_…"
}'

Example response

{
  "deploy_state": "draft",
  "name": "front-desk"
}

POST /v1/agents/{name}/test#

Start a test session. Mints a short-lived session so you can talk to the agent in the browser without a phone call. Returns a room + join token. A test session is a call: it spends one of your plan's simultaneous-call slots for as long as it runs.

Parameters

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/agents/{name}/test" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "expires_at": "2026-07-15T12:00:00Z",
  "room_name": "room_…",
  "session_id": "sess_…"
}

GET /v1/agents/{name}/versions#

List agent versions. Every save snapshots the agent. Returns the version history, newest first, at most 500 versions; each item is the version's metadata (read one version for its spec).

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/versions" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "items": [
    {
      "created_at": "2026-07-14T09:00:00Z",
      "version_id": "v_…"
    }
  ]
}

GET /v1/agents/{name}/versions/{version_id}#

Get an agent version. Returns a specific snapshot including its full spec.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/agents/{name}/versions/{version_id}" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "spec": {
    "name": "front-desk"
  },
  "version_id": "v_…"
}

Schemas#

Agent#

A voice agent. POST this shape to create or update an agent; server-managed knobs are filled from your account defaults.

AgentGenerateRequest#

CDRExport#

CallWebhook#

CustomField#

EmailNotification#

Error#

Error envelope returned for non-2xx responses.

EventWebhook#

EventWebhooks#

Identity#

The agent's system prompt and opening line.

Intent#

IntentTaxonomy#

Language#

Notifications#

RollbackRequest#

SearchWidget#

Public knowledge-search box for your own site. It serves anonymous visitors, so it is switched on separately from the chat bubble and must name both the sites that may embed it and the collections it may search.

TransferWebhook#

Voice#

WebWidget#

WebWidgetBackground#

WebWidgetFormField#

WebWidgetPreForm#

WebWidgetTakeover#

WebWidgetTheme#