Agents

Die Beschreibungen der Endpoints und der Felder erscheinen auf Englisch, genau so, wie die API sie ausliefert. Das ist Absicht: Sie lesen hier, was Sie auch in den Antworten sehen.

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.

Antworten

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json Schema: Agent

Antworten

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json Schema: AgentGenerateRequest

Antworten

Beispielanfrage

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

Beispielantwort

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

Anfragetext

application/json

Antworten

Beispielanfrage

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

Beispielantwort

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

DELETE /v1/agents/{name}#

Delete an agent. Permanently deletes the agent.

Parameter

Antworten

Beispielanfrage

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.

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

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

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

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

Parameter

Anfragetext

application/json Schema: RollbackRequest

Antworten

Beispielanfrage

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

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

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

Parameter

Antworten

Beispielanfrage

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

Beispielantwort

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

Schemata#

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#