Agents

Le descrizioni degli endpoint e dei campi restano in inglese, esattamente come le pubblica l'API. È una scelta voluta: qui legge ciò che vedrà anche nelle risposte.

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.

Risposte

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json Schema: Agent

Risposte

Esempio di richiesta

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"
  }
}'

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json Schema: AgentGenerateRequest

Risposte

Esempio di richiesta

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
}'

Esempio di risposta

{
  "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.

Corpo della richiesta

application/json

Risposte

Esempio di richiesta

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"
  }
}'

Esempio di risposta

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

DELETE /v1/agents/{name}#

Delete an agent. Permanently deletes the agent.

Parametri

Risposte

Esempio di richiesta

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.

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

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

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

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

Parametri

Corpo della richiesta

application/json Schema: RollbackRequest

Risposte

Esempio di richiesta

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_…"
}'

Esempio di risposta

{
  "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.

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

{
  "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).

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

{
  "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.

Parametri

Risposte

Esempio di richiesta

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

Esempio di risposta

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

Schemi#

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#