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

Update an agent

Delete an agent DELETE

Deletes the agent and its widget configurations and tool assignments. Its phone number becomes unassigned. Past conversations are kept.

Assign a phone number to an agent POST

Calls to the number are then answered by this agent. An agent has at most one number; assigning another replaces it. The number must belong to the agent's tenant and not be assigned to another agent.

PUT
/v1/tenants/{tenantId}/agents/{id}

Replaces the agent's settings. Send the version you read; it changes on every update. Voice settings left null keep their current value. knowledgeBaseIds: null keeps the current links, [] removes all, a list replaces them. The tenant cannot be changed.

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.

id*string

Agent id.

Request Body

New values.

  1. body
  1. body
  2. …

New values for an agent. Fields are replaced; voice settings left null keep their current value.

version?integer

The version you read. A stale version gives 409.

Formatint32
name*string

Display name.

description?string

Internal description; not given to the AI.

instructions?string

System prompt.

variableDefinitionsJson?string

Prompt variables as a JSON-encoded string (see Agent.variableDefinitionsJson).

status?string

Lifecycle status; null keeps the current value.

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

Realtime model; null keeps the current value.

voice?string

Voice; null keeps the current value.

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

null keeps the current links, [] removes all, a list replaces them.

allowFollowUpEmail?boolean

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

followUpEmailAddress?string

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

allowCallTransfer?boolean

Give the AI a transfer_call tool on phone calls.

callTransferType?string

How calls are transferred; null keeps the current value.

Value in"direct""semi_attended"
isTemplate?boolean

Whether the agent is a template.

type?string

Optional free-text label.

allowEndCall?boolean

Give the AI an end_call tool.

turnDetectionType?string

server_vad, semantic_vad or none.

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

semantic_vad only.

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

server_vad only, 0.0–1.0.

Formatdouble
turnDetectionPrefixPadding?integer

server_vad only, milliseconds.

Formatint32
turnDetectionSilenceDuration?integer

server_vad only, milliseconds.

Formatint32
turnDetectionTimeout?boolean

server_vad only: speak up after user silence.

turnDetectionTimeoutTime?integer

Idle timeout in milliseconds.

Formatint32
turnDetectionInterruptResponse?boolean

Let the user interrupt the AI.

transcriptionModel?string

gpt-4o-transcribe, gpt-4o-mini-transcribe or off.

transcriptionLanguage?string

ISO 639-1 code or auto.

transcriptionInstructions?string

Hints for the transcriber. Replaced as given (null clears).

noiseReductionType?string

near_field, far_field or none.

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

Ignored; use PUT /v1/tenants/{tenantId}/agents/{id}/tools.

Response Body

Updated.

Example Request
curl -X PUT 'https://api.envocal.ai/v1/tenants/string/agents/string' \  -H 'Content-Type: application/json' \  -d '{  "name": "string"}'
Example Response
Empty
Example Request
curl -X PUT 'https://api.envocal.ai/v1/tenants/string/agents/string' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "string"
}'