DocumentationAPI ReferenceChangelog

Envocal API

API Reference API Changelog

Endpoints

List agents of a tenant GETCreate an agent POSTGet an agent GETDelete an agent DELETEUpdate an agent PUTAssign a phone number to an agent POSTUnassign an agent's phone number DELETEList an agent's knowledge bases GETLink a knowledge base to an agent POSTUnlink a knowledge base from an agent DELETEList agent templates GETCreate an agent from a template POST
Agents

Create an agent

List agents of a tenant GET

Requires agents:read

Get an agent GET

The agent's settings. Use GET /v1/agents/{id}/full to also get its knowledge bases and tools expanded.

POST
/v1/tenants/{tenantId}/agents

Creates the agent in the tenant together with a default widget configuration whose settings are all unset (the widget's defaults apply; change them with PUT /v1/tenants/{tenantId}/agents/{agentId}/widget-configs/{id}). Omitted voice settings get defaults (server_vad turn detection, gpt-4o-transcribe transcription, far_field noise reduction). Assign tools with PUT /v1/tenants/{tenantId}/agents/{id}/tools and a phone number with POST /v1/tenants/{tenantId}/agents/{agentId}/phone-numbers/{phoneNumberId}.

Required permission: agents:write

Authorization

Bearer
headerAuthorizationBearer <token>

Tenant API key (evk_…), created in Studio → Vault → API keys.

Path Parameters

tenantId*string

Tenant id, or current for the key's own tenant. Must be the key's tenant or one of its sub-tenants.

Request Body

The new agent.

  1. body
  1. body
  2. …

A new agent. Omitted optional fields get defaults.

name*string

Display name.

description?string

Internal description; not given to the AI.

instructions?string

System prompt. May reference prompt variables as {{name}} and system variables such as {{system_caller_number}}.

variableDefinitionsJson?string

Prompt variables as a JSON-encoded string: an array of {"name", "jsonType", "placeholder", "description", "required"}.

status?string

Lifecycle status. Default draft.

Value in"draft""active""archived"
model?string

Realtime model, e.g. gpt-realtime. Omit for the platform default.

voice?string

Voice for speech output.

Value in"alloy""ash""ballad""coral""echo""sage""shimmer""verse""marin""cedar"
knowledgeBaseIds?array<string>

Knowledge bases to link; they must belong to tenantId.

allowFollowUpEmail?boolean

Give the AI a send_email tool for follow-up emails. Default false.

followUpEmailAddress?string

Follow-up email recipient; required when allowFollowUpEmail is true.

allowCallTransfer?boolean

Give the AI a transfer_call tool on phone calls. Default true.

callTransferType?string

How calls are transferred. Default direct.

Value in"direct""semi_attended"
isTemplate?boolean

Make this agent a template for this tenant and its sub-tenants. Default false.

type?string

Optional free-text label; not used by the platform.

allowEndCall?boolean

Give the AI an end_call tool. Default false.

turnDetectionType?string

server_vad (default), semantic_vad or none.

Value in"server_vad""semantic_vad""none"
turnDetectionEagerness?string

semantic_vad only. Default auto.

Value in"auto""low""medium""high"
turnDetectionThreshold?number

server_vad only, 0.0–1.0. Default 0.5.

Formatdouble
turnDetectionPrefixPadding?integer

server_vad only, milliseconds. Default 300.

Formatint32
turnDetectionSilenceDuration?integer

server_vad only, milliseconds. Default 500.

Formatint32
turnDetectionTimeout?boolean

server_vad only: speak up after a period of user silence. Default false.

turnDetectionTimeoutTime?integer

Idle timeout in milliseconds; required when turnDetectionTimeout is true.

Formatint32
turnDetectionInterruptResponse?boolean

Let the user interrupt the AI. Default true.

transcriptionModel?string

gpt-4o-transcribe (default), gpt-4o-mini-transcribe or off.

transcriptionLanguage?string

ISO 639-1 code or auto (default).

transcriptionInstructions?string

Optional hints for the transcriber.

noiseReductionType?string

near_field, far_field (default) or none.

Value in"none""near_field""far_field"
toolAssignments?

Ignored; assign tools with PUT /v1/tenants/{tenantId}/agents/{id}/tools after creating the agent.

Response Body

Created. The Location header points to the new agent.

  1. response
  1. response
  2. …

An AI voice/chat agent.

id*string

Agent id.

version?integer

Concurrency version. Send it back when updating; it increases on every update.

Formatint32
name*string

Display name.

description?string

Internal description for people; not given to the AI.

instructions?string

System prompt for the AI. May reference prompt variables as {{name}} (see variableDefinitionsJson) and system variables such as {{system_caller_number}}.

variableDefinitionsJson?string

Prompt variables as a JSON-encoded string: an array of {"name", "jsonType", "placeholder", "description", "required"}. Referenced as {{name}} in the instructions and filled at conversation time (e.g. from tool output); placeholder is used when no value is available.

status?string

Lifecycle status.

Value in"draft""active""archived"
model?string

Realtime model, e.g. gpt-realtime or gpt-realtime-1.5. Empty means the platform default.

voice?string

Voice used for speech output.

Value in"alloy""ash""ballad""coral""echo""sage""shimmer""verse""marin""cedar"
knowledgeBaseIds?array<string>

Ids of linked knowledge bases.

phoneNumberId?string

Id of the assigned phone number, if any. Change it with the agent phone-number endpoints.

phoneNumber?string

The assigned phone number in E.164 format (read only).

allowFollowUpEmail?boolean

Give the AI a send_email tool that emails conversation details to followUpEmailAddress.

followUpEmailAddress?string

Recipient of follow-up emails (e.g. a team inbox). Required when allowFollowUpEmail is true.

allowCallTransfer?boolean

Give the AI a transfer_call tool on phone calls.

callTransferType?string

How phone calls are transferred.

Value in"direct""semi_attended"
isTemplate?boolean

When true the agent is a template that this tenant and its sub-tenants can create agents from.

type?string

Optional free-text label for your own classification; not used by the platform.

allowEndCall?boolean

Give the AI an end_call tool to end the conversation after saying goodbye.

tenantId*string

Tenant the agent belongs to (cannot be changed).

turnDetectionType?string

How the AI decides the user finished speaking: server_vad (silence based), semantic_vad (meaning based) or none (no automatic turn taking).

Value in"server_vad""semantic_vad""none"
turnDetectionEagerness?string

semantic_vad only: how quickly the AI responds.

Value in"auto""low""medium""high"
turnDetectionThreshold?number

server_vad only: speech detection sensitivity, 0.0–1.0 (higher needs louder speech). Default 0.5.

Formatdouble
turnDetectionPrefixPadding?integer

server_vad only: milliseconds of audio kept before detected speech. Default 300.

Formatint32
turnDetectionSilenceDuration?integer

server_vad only: milliseconds of silence that end the user's turn. Default 500.

Formatint32
turnDetectionTimeout?boolean

server_vad only: when true, the AI speaks up after turnDetectionTimeoutTime of user silence.

turnDetectionTimeoutTime?integer

Idle timeout in milliseconds; required when turnDetectionTimeout is true.

Formatint32
turnDetectionInterruptResponse?boolean

Whether the user can interrupt the AI while it is speaking. Default true.

transcriptionModel?string

Speech-to-text model for transcripts: gpt-4o-transcribe (precision) or gpt-4o-mini-transcribe (speed). off disables transcription.

transcriptionLanguage?string

Expected language as an ISO 639-1 code (e.g. sv, en), or auto to detect.

transcriptionInstructions?string

Optional hints for the transcriber, e.g. product names or spelling.

noiseReductionType?string

Input noise reduction: near_field (headsets, phones), far_field (laptops, rooms) or none.

Value in"none""near_field""far_field"
toolAssignments?

Not filled here; use GET /v1/tenants/{tenantId}/agents/{id}/tools.

Example Request
curl -X POST 'https://api.envocal.ai/v1/tenants/string/agents' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
{  "id": "string",  "version": 0,  "name": "string",  "description": "string",  "instructions": "string",  "variableDefinitionsJson": "string",  "status": "draft",  "model": "string",  "voice": "alloy",  "knowledgeBaseIds": [    "string"  ],  "phoneNumberId": "string",  "phoneNumber": "string",  "allowFollowUpEmail": true,  "followUpEmailAddress": "string",  "allowCallTransfer": true,  "callTransferType": "direct",  "isTemplate": true,  "type": "string",  "allowEndCall": true,  "tenantId": "string",  "turnDetectionType": "server_vad",  "turnDetectionEagerness": "auto",  "turnDetectionThreshold": 0.1,  "turnDetectionPrefixPadding": 0,  "turnDetectionSilenceDuration": 0,  "turnDetectionTimeout": true,  "turnDetectionTimeoutTime": 0,  "turnDetectionInterruptResponse": true,  "transcriptionModel": "string",  "transcriptionLanguage": "string",  "transcriptionInstructions": "string",  "noiseReductionType": "none",  "toolAssignments": {    "before": [      "8e6267db-32ed-454a-a2cc-6beef2f6f00e"    ],    "during": [      "e3ae3f0a-5397-4416-b273-f7833a7fddc8"    ],    "after": [      "3f00dd4a-56f2-49c5-940c-69eed8a9fb5b"    ]  }}
Example Request
curl -X POST 'https://api.envocal.ai/v1/tenants/string/agents' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'
{
  "id": "string",
  "version": 0,
  "name": "string",
  "description": "string",
  "instructions": "string",
  "variableDefinitionsJson": "string",
  "status": "draft",
  "model": "string",
  "voice": "alloy",
  "knowledgeBaseIds": [
    "string"
  ],
  "phoneNumberId": "string",
  "phoneNumber": "string",
  "allowFollowUpEmail": true,
  "followUpEmailAddress": "string",
  "allowCallTransfer": true,
  "callTransferType": "direct",
  "isTemplate": true,
  "type": "string",
  "allowEndCall": true,
  "tenantId": "string",
  "turnDetectionType": "server_vad",
  "turnDetectionEagerness": "auto",
  "turnDetectionThreshold": 0.1,
  "turnDetectionPrefixPadding": 0,
  "turnDetectionSilenceDuration": 0,
  "turnDetectionTimeout": true,
  "turnDetectionTimeoutTime": 0,
  "turnDetectionInterruptResponse": true,
  "transcriptionModel": "string",
  "transcriptionLanguage": "string",
  "transcriptionInstructions": "string",
  "noiseReductionType": "none",
  "toolAssignments": {
    "before": [
      "8e6267db-32ed-454a-a2cc-6beef2f6f00e"
    ],
    "during": [
      "e3ae3f0a-5397-4416-b273-f7833a7fddc8"
    ],
    "after": [
      "3f00dd4a-56f2-49c5-940c-69eed8a9fb5b"
    ]
  }
}