Agents

Οι περιγραφές των endpoints και των πεδίων εμφανίζονται στα αγγλικά, όπως ακριβώς τις δημοσιεύει το API. Είναι επιλογή μας, ώστε να διαβάζετε εδώ ό,τι θα δείτε και στις αποκρίσεις.

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.

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Σώμα αιτήματος

application/json Σχήμα: Agent

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Σώμα αιτήματος

application/json Σχήμα: AgentGenerateRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Σώμα αιτήματος

application/json

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

DELETE /v1/agents/{name}#

Delete an agent. Permanently deletes the agent.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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.

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

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

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

Παράμετροι

Σώμα αιτήματος

application/json Σχήμα: RollbackRequest

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Παράμετροι

Αποκρίσεις

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Σχήματα#

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#