> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verbex.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Update AI Agent
> Update an agent and return the full updated agent.
**The v2 equivalent, [`PUT /v2/ai-agents/{agent_id}`](/api-reference/ai-agents-v2/update-ai-agent), is deprecated and stops working on November 30, 2026.** This is the v3 endpoint. [Migrate from v2 to v3](/api-reference/ai-agents-v3/migrate-from-v2) before that date.
## Partial updates
Although this is a `PUT`, the update **merges**. Fields present in the body are applied. Fields you omit keep their stored value. Nested objects (`llm`, `stt`, `tts`) merge the same way, so `{"tts": {"provider_id": "…", "voice_id": "…"}}` changes the voice and keeps the rest of the TTS configuration. You cannot clear a field by omitting it.
`llm.graph_data` is the exception: it is not merged. A sent `graph_data` replaces the stored graph as a whole.
## Changing the LLM, STT model or voice
Selections use the same id-based contract as [Create AI Agent](/api-reference/ai-agents-v3/create-ai-agent):
- Send `stt.provider_id` + `stt.model_id` or `tts.provider_id` + `tts.voice_id`. The reference is resolved again against the provider catalog, and the stored names are refreshed.
- Send `llm.llm_id`, or `graph_data.agentDefaults.llm.llm_id` for a `flow` agent. The LLM fields on the agent are refreshed from the model catalog.
## Flow agents
- To change a flow agent's default STT model, LLM or voice, send `llm.llm_type: "flow"` and the **complete** `llm.graph_data` with the new ids in `agentDefaults`. A partial graph replaces the stored one. See the `flow_graph` request example.
- `graph_data` without `llm.llm_type` returns `422`.
- The server fills provider, model and voice names into the graph, then validates it. An id the catalog does not know returns `422` with the graph path in `error_details`, for example `llm.graph_data.agentDefaults.tts.voice_id`.
- Root `stt` and `tts` are not used by flow agents.
The same `422` checks as create apply: the referenced record must exist, be `ACTIVE`, support the agent's `llm_type` and, for a custom model, belong to your organization.
## Rejected LLM fields
`llm.model_provider`, `llm.model_name` and `llm.model_display_name` are not accepted. The model is chosen by `llm.llm_id` alone, and those fields are always refilled from the catalog. A request that sends any of them returns `400`, and every offending field is named in `error_details`:
```json
{
"status": "error",
"message": "Agent validation failed",
"error_details": {
"llm.model_name": "llm.model_name is not accepted on v3 update; send llm.llm_id to change the model"
}
}
```
[Get AI Agent](/api-reference/ai-agents-v3/get-ai-agent) returns those three fields inside `data.llm`. A client that reads an agent and sends the same `llm` object back gets this `400`. Remove the three fields, or send only the fields you change.
## Field notes
- `model_temperature`: when omitted, the stored value is kept, **even when `llm_id` changes**. The new model's temperature applies only if the agent had none. A sent value, `0` included, is stored as is.
- `vad_activation_threshold`: omitting the key keeps the stored value. A number from `0.10` to `0.90` replaces it.
- `wait_time_before_detecting_end_of_speech` and `max_endpointing_delay` apply to `flow` agents only. When a request changes either one, `max_endpointing_delay` must stay greater than the wait time after the merge, otherwise the request returns `422`.
**Sending `vad_activation_threshold: null` does not clear the stored value yet.** The response shows the key removed, but the stored value stays and later reads and calls keep using it. Until a fix ships, you can set a new value but cannot clear one.
## Versioning
Every successful update writes a new agent version. The response carries `current_version` and, when the version has a label, `current_version_name`.
## Response envelope
Every v3 response uses the same envelope:
| Field | Meaning |
| --- | --- |
| `status` | `success` or `error`. Always lowercase. |
| `message` | A human-readable summary. |
| `data` | The result. Absent on errors. |
| `error_details` | A map from field path to message. Present only on some errors. |
Fields with no value are omitted rather than returned as `null`.
The response message and `operation_type` depend on the agent type: `Simple agent updated successfully` / `UPDATE`, `Flow builder agent updated successfully` / `UPDATE_FLOW_BUILDER`, or `Agentic agent updated successfully` / `UPDATE_AGENTIC`.
## Status codes
| Code | When |
| --- | --- |
| `200` | Updated. The body carries the full agent. |
| `400` | The request sent `llm.model_provider`, `llm.model_name` or `llm.model_display_name`. |
| `403` | The agent belongs to another organization or workspace. |
| `404` | No such agent. |
| `422` | Validation failed, or a referenced catalog record was missing, inactive or incompatible. |
## OpenAPI
````yaml /api-reference/openapi.json put /v3/ai-agents/{agent_id}
openapi: 3.1.0
info:
title: Verbex Platform API
description: API for managing AI agents, calls, phone numbers, and more.
version: 1.0.0
servers: []
security: []
tags:
- name: Knowledge Bases
description: >-
Create and manage knowledge bases, ingest documents into them, and search
them semantically.
**Authentication.** Every request carries a bearer token: `Authorization:
Bearer `. That is the only credential a client sends. The
gateway resolves your identity from it and injects the tenant headers the
service reads internally, so clients never send `x-user-org-id` or
`x-verbex-id` themselves.
**Tenancy is enforced on every route.** A knowledge base belongs to one
organization and one user. Requesting one your token does not own returns
`404 Knowledge base not found`, never `403`. This is deliberate: a
nonexistent ID, a malformed ID and someone else's ID are indistinguishable
in the response, so the API cannot be used to probe for other tenants'
data. If you get a `404` on an ID you are certain exists, suspect the
token before you suspect the ID.
**Ingestion is asynchronous.** File upload and website crawl both answer
`202` as soon as the material is stored and the job is queued. Parsing,
chunking, embedding and indexing happen afterwards in a worker. Poll the
document status endpoint until it reports `completed` before expecting
search to see the content. That gap is the most common source of "why
isn't my data showing up".
**There is no document update endpoint.** Every submission mints a new
`document_id`, so re-uploading a file or re-crawling the same URLs creates
a second document while the first remains. To refresh material, delete
then resubmit — and note that the sequence is not atomic.
- name: AI Agents v3
description: >-
Create, read, update and delete AI agents. v3 selects the LLM,
speech-to-text model and voice by catalog id, and wraps every response in
a standard envelope. It replaces the deprecated AI Agents v2 operations,
which stop working on November 30, 2026. See [Migrate from v2 to
v3](/api-reference/ai-agents-v3/migrate-from-v2).
- name: LLM Models
description: >-
The LLM model catalog. Look up the `llm_model_id` to send as `llm.llm_id`
when you create or update an agent.
- name: Speech Providers
description: >-
The speech-to-text and text-to-speech provider catalogs. Look up the
`provider_id`, `model_id` and `voice_id` to send when you create or update
an agent.
paths:
/v3/ai-agents/{agent_id}:
put:
tags:
- AI Agents v3
summary: Update AI Agent
description: >-
Update an agent and return the full updated agent.
**The v2 equivalent, [`PUT
/v2/ai-agents/{agent_id}`](/api-reference/ai-agents-v2/update-ai-agent),
is deprecated and stops working on November 30, 2026.** This is the v3
endpoint. [Migrate from v2 to
v3](/api-reference/ai-agents-v3/migrate-from-v2) before that date.
## Partial updates
Although this is a `PUT`, the update **merges**. Fields present in the
body are applied. Fields you omit keep their stored value. Nested
objects (`llm`, `stt`, `tts`) merge the same way, so `{"tts":
{"provider_id": "…", "voice_id": "…"}}` changes the voice and keeps the
rest of the TTS configuration. You cannot clear a field by omitting it.
`llm.graph_data` is the exception: it is not merged. A sent `graph_data`
replaces the stored graph as a whole.
## Changing the LLM, STT model or voice
Selections use the same id-based contract as [Create AI
Agent](/api-reference/ai-agents-v3/create-ai-agent):
- Send `stt.provider_id` + `stt.model_id` or `tts.provider_id` +
`tts.voice_id`. The reference is resolved again against the provider
catalog, and the stored names are refreshed.
- Send `llm.llm_id`, or `graph_data.agentDefaults.llm.llm_id` for a
`flow` agent. The LLM fields on the agent are refreshed from the model
catalog.
## Flow agents
- To change a flow agent's default STT model, LLM or voice, send
`llm.llm_type: "flow"` and the **complete** `llm.graph_data` with the
new ids in `agentDefaults`. A partial graph replaces the stored one. See
the `flow_graph` request example.
- `graph_data` without `llm.llm_type` returns `422`.
- The server fills provider, model and voice names into the graph, then
validates it. An id the catalog does not know returns `422` with the
graph path in `error_details`, for example
`llm.graph_data.agentDefaults.tts.voice_id`.
- Root `stt` and `tts` are not used by flow agents.
The same `422` checks as create apply: the referenced record must exist,
be `ACTIVE`, support the agent's `llm_type` and, for a custom model,
belong to your organization.
## Rejected LLM fields
`llm.model_provider`, `llm.model_name` and `llm.model_display_name` are
not accepted. The model is chosen by `llm.llm_id` alone, and those
fields are always refilled from the catalog. A request that sends any of
them returns `400`, and every offending field is named in
`error_details`:
```json
{
"status": "error",
"message": "Agent validation failed",
"error_details": {
"llm.model_name": "llm.model_name is not accepted on v3 update; send llm.llm_id to change the model"
}
}
```
[Get AI Agent](/api-reference/ai-agents-v3/get-ai-agent) returns those
three fields inside `data.llm`. A client that reads an agent and sends
the same `llm` object back gets this `400`. Remove the three fields, or
send only the fields you change.
## Field notes
- `model_temperature`: when omitted, the stored value is kept, **even
when `llm_id` changes**. The new model's temperature applies only if the
agent had none. A sent value, `0` included, is stored as is.
- `vad_activation_threshold`: omitting the key keeps the stored value. A
number from `0.10` to `0.90` replaces it.
- `wait_time_before_detecting_end_of_speech` and `max_endpointing_delay`
apply to `flow` agents only. When a request changes either one,
`max_endpointing_delay` must stay greater than the wait time after the
merge, otherwise the request returns `422`.
**Sending `vad_activation_threshold: null` does not clear the stored
value yet.** The response shows the key removed, but the stored value
stays and later reads and calls keep using it. Until a fix ships, you
can set a new value but cannot clear one.
## Versioning
Every successful update writes a new agent version. The response carries
`current_version` and, when the version has a label,
`current_version_name`.
## Response envelope
Every v3 response uses the same envelope:
| Field | Meaning |
| --- | --- |
| `status` | `success` or `error`. Always lowercase. |
| `message` | A human-readable summary. |
| `data` | The result. Absent on errors. |
| `error_details` | A map from field path to message. Present only on
some errors. |
Fields with no value are omitted rather than returned as `null`.
The response message and `operation_type` depend on the agent type:
`Simple agent updated successfully` / `UPDATE`, `Flow builder agent
updated successfully` / `UPDATE_FLOW_BUILDER`, or `Agentic agent updated
successfully` / `UPDATE_AGENTIC`.
## Status codes
| Code | When |
| --- | --- |
| `200` | Updated. The body carries the full agent. |
| `400` | The request sent `llm.model_provider`, `llm.model_name` or
`llm.model_display_name`. |
| `403` | The agent belongs to another organization or workspace. |
| `404` | No such agent. |
| `422` | Validation failed, or a referenced catalog record was missing,
inactive or incompatible. |
operationId: update_ai_agent_v3
parameters:
- $ref: '#/components/parameters/V3AgentId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateAIAgentV3Request'
examples:
rename:
summary: Rename only
value:
agent_name: Tier-1 Support Agent
swap_voice:
summary: Switch to a different TTS voice
value:
tts:
provider_id: 6a5c079f814b8ed08b15172b
voice_id: EXAVITQu4vr4xnSDxMaL
full:
summary: 'Simple agent: every updatable field'
value:
agent_name: Customer Support Agent
language_code: en-US
agent_status: ACTIVE
llm:
llm_id: 9d259647-d5ec-423d-96a9-2750980e8ecb
llm_type: simple
system_prompt: You are a helpful customer support assistant.
model_temperature: 0.1
stt:
provider_id: 6a5c45808d2d94e9d0e255d3
model_id: af97a5f7-0f10-4eb3-a915-f7fe95a050f8
tts:
provider_id: 6a5c079f814b8ed08b15172b
voice_id: IKne3meq5aSn9XLyUdCD
voice_temperature: 1
speech_speed: 0.9
vad_activation_threshold: 0.4
knowledge_base_id: kb-123456
enable_user_interruptions: true
minimum_speech_duration_for_interruptions: 0.5
minimum_words_before_interruption: 2
interruption_mode: vad
ambient_sound: office
ambient_sound_volume: 1
webhook_url: https://api.example.com/webhooks/call-events
end_call_after_silence_seconds: 20
max_call_duration_seconds: 600
welcome_message: Hello! Thanks for calling. How can I help you today?
end_call_instruction: End the call politely once the issue is resolved.
amd_voicemail_message: Sorry we missed you. Please call us back.
voicemail_detection_timeout_seconds: 5
agent_ended_call_delay_seconds: 1
welcome_message_delay_in_seconds: 0.5
enable_amd: true
silence_reminder_enabled: true
silence_reminder_duration_seconds: 15
max_number_of_silence_reminders: 3
interval_between_silence_reminders_seconds: 10
enable_noise_cancellation: true
dynamic_data_config:
- name: customer_data
url: https://api.example.com/customer-data
method: GET
timeout: 2000
cache: true
response_data:
- name: customer_name
data: $.customer.name
context: Customer's full name for personalization
post_call_analysis:
- type: string
name: call_summary
description: A brief summary of the call and key points.
examples:
- Customer asked about billing; issue resolved.
pronunciations:
- id: r1
term: API
replacement: ay pee eye
flow_graph:
summary: 'Flow agent: change the default voice'
description: >-
`graph_data` replaces the stored graph as a whole, so send the
complete graph. `llm.llm_type` is required whenever
`graph_data` is sent.
value:
llm:
llm_type: flow
graph_data:
entryNodeId: node-start
nodes:
- id: node-start
type: start
position:
x: 300
'y': 50
data:
label: Start
userAwayTimeoutSec: 30
maxToolSteps: 3
- id: conv
type: conversation
position:
x: 300
'y': 200
data:
label: Conversation
mode: full
instructions: You are a helpful assistant.
openingMessage:
type: llm-generated
instructions: Greet the user and ask how you can help.
modelConfig:
stt:
source: flow-default
llm:
source: flow-default
tts:
source: flow-default
allowEndCall: true
- id: end
type: end-call
position:
x: 300
'y': 350
data:
label: End call
farewellMessage:
type: none
edges:
- id: e1
source: node-start
target: conv
label: Start
kind: session-start
contextPassing: full
- id: e2
source: conv
target: end
label: End Call
kind: conditional-edge
decisionType: llm
promptCondition: When the user wants to end the call
contextPassing: full
variables: []
globalNodeIds: []
agentDefaults:
stt:
provider_id: 6a5c45808d2d94e9d0e255d3
model_id: aec2493a-eba9-48d0-9e64-4aab4437f7f5
llm:
llm_id: d6847c0b-179f-4910-b4f5-a1bee9807a57
tts:
provider_id: 6a5c079f814b8ed08b15172b
voice_id: EXAVITQu4vr4xnSDxMaL
language: en
flow_timing:
summary: 'Flow agent: change end-of-speech timing'
description: >-
`max_endpointing_delay` must stay greater than
`wait_time_before_detecting_end_of_speech`.
value:
wait_time_before_detecting_end_of_speech: 0.3
max_endpointing_delay: 2.5
responses:
'200':
description: Agent updated
content:
application/json:
schema:
$ref: '#/components/schemas/V3ApiResponseAIAgent'
examples:
simple:
summary: Simple agent (after the `full` request)
value:
status: success
message: Simple agent updated successfully
data:
ai_agent_id: 3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42
agent_name: Customer Support Agent
agent_status: ACTIVE
language_code: en-US
llm:
llm_id: 9d259647-d5ec-423d-96a9-2750980e8ecb
llm_type: simple
model_provider: openai
model_name: gpt-4o-mini
model_display_name: GPT-4o mini
model_temperature: 0.1
max_tokens: 4096
system_prompt: You are a helpful customer support assistant.
stt:
provider_id: 6a5c45808d2d94e9d0e255d3
provider: deepgram
model_id: af97a5f7-0f10-4eb3-a915-f7fe95a050f8
model: nova-3-general
tts:
provider_id: 6a5c079f814b8ed08b15172b
provider: elevenlabs
voice_id: IKne3meq5aSn9XLyUdCD
voice_name: Charlie
model_name: eleven_flash_v2_5
voice_temperature: 1
speech_speed: 0.9
vad_activation_threshold: 0.4
knowledge_base_id: kb-123456
enable_user_interruptions: true
minimum_speech_duration_for_interruptions: 0.5
minimum_words_before_interruption: 2
interruption_mode: vad
ambient_sound: office
ambient_sound_volume: 1
webhook_url: https://api.example.com/webhooks/call-events
end_call_after_silence_seconds: 20
max_call_duration_seconds: 600
welcome_message: Hello! Thanks for calling. How can I help you today?
end_call_instruction: End the call politely once the issue is resolved.
amd_voicemail_message: Sorry we missed you. Please call us back.
voicemail_detection_timeout_seconds: 5
agent_ended_call_delay_seconds: 1
welcome_message_delay_in_seconds: 0.5
enable_amd: true
silence_reminder_enabled: true
silence_reminder_duration_seconds: 15
max_number_of_silence_reminders: 3
interval_between_silence_reminders_seconds: 10
enable_noise_cancellation: true
dynamic_data_config:
- name: customer_data
url: https://api.example.com/customer-data
method: GET
timeout: 2000
cache: true
response_data:
- name: customer_name
data: $.customer.name
context: Customer's full name for personalization
post_call_analysis:
- type: string
name: call_summary
description: A brief summary of the call and key points.
examples:
- Customer asked about billing; issue resolved.
pronunciations:
- id: r1
term: API
replacement: ay pee eye
organization_id: org_7f3a9c
agent_owner_id: usr_12ab34
created_by_user_id: usr_12ab34
created_at: '2026-10-15T09:30:12.481Z'
modified_at: '2026-10-15T10:02:47.115Z'
current_version: 2
operation_type: UPDATE
flow:
summary: Flow agent (after the `flow_graph` request)
value:
status: success
message: Flow builder agent updated successfully
data:
ai_agent_id: 5b1e9d7c-2f4a-4e6b-8c3d-1a2b3c4d5e6f
agent_name: New Flow Agent
agent_status: ACTIVE
language_code: en-US
llm:
llm_id: d6847c0b-179f-4910-b4f5-a1bee9807a57
llm_type: flow
model_provider: openai
model_name: gpt-4o-mini
model_display_name: GPT-4o mini
model_temperature: 0.7
max_tokens: 4096
graph_data:
entryNodeId: node-start
nodes:
- id: node-start
type: start
position:
x: 300
'y': 50
data:
label: Start
userAwayTimeoutSec: 30
maxToolSteps: 3
- id: conv
type: conversation
position:
x: 300
'y': 200
data:
label: Conversation
mode: full
instructions: You are a helpful assistant.
openingMessage:
type: llm-generated
instructions: Greet the user and ask how you can help.
modelConfig:
stt:
source: flow-default
llm:
source: flow-default
tts:
source: flow-default
allowEndCall: true
- id: end
type: end-call
position:
x: 300
'y': 350
data:
label: End call
farewellMessage:
type: none
edges:
- id: e1
source: node-start
target: conv
label: Start
kind: session-start
contextPassing: full
- id: e2
source: conv
target: end
label: End Call
kind: conditional-edge
decisionType: llm
promptCondition: When the user wants to end the call
contextPassing: full
variables: []
globalNodeIds: []
agentDefaults:
stt:
provider_id: 6a5c45808d2d94e9d0e255d3
model_id: aec2493a-eba9-48d0-9e64-4aab4437f7f5
provider: deepgram
model: nova-3
llm:
llm_id: d6847c0b-179f-4910-b4f5-a1bee9807a57
provider: openai
model: gpt-4o-mini
tts:
provider_id: 6a5c079f814b8ed08b15172b
voice_id: EXAVITQu4vr4xnSDxMaL
provider: elevenlabs
voice: EXAVITQu4vr4xnSDxMaL
model: eleven_flash_v2_5
language: en
speech_speed: 0.8
vad_activation_threshold: 0.5
wait_time_before_detecting_end_of_speech: 0.2
max_endpointing_delay: 2
enable_user_interruptions: true
minimum_speech_duration_for_interruptions: 0.5
minimum_words_before_interruption: 2
interruption_mode: vad
ambient_sound: none
ambient_sound_volume: 1
end_call_after_silence_seconds: 10
max_call_duration_seconds: 1800
voicemail_detection_timeout_seconds: 90
agent_ended_call_delay_seconds: 2
welcome_message_delay_in_seconds: 2
enable_amd: false
silence_reminder_enabled: false
silence_reminder_duration_seconds: 10
max_number_of_silence_reminders: 3
interval_between_silence_reminders_seconds: 10
organization_id: org_7f3a9c
created_by_user_id: usr_12ab34
created_at: '2026-10-15T09:41:03.220Z'
modified_at: '2026-10-15T10:05:19.604Z'
current_version: 2
operation_type: UPDATE_FLOW_BUILDER
'400':
description: >-
The request sent catalog LLM name fields; send `llm.llm_id` to
change the model
content:
application/json:
schema:
$ref: '#/components/schemas/V3ErrorResponse'
example:
status: error
message: Agent validation failed
error_details:
llm.model_provider: >-
llm.model_provider is not accepted on v3 update; send
llm.llm_id to change the model
llm.model_name: >-
llm.model_name is not accepted on v3 update; send llm.llm_id
to change the model
llm.model_display_name: >-
llm.model_display_name is not accepted on v3 update; send
llm.llm_id to change the model
'403':
description: >-
The agent exists but is outside the caller's organization or
workspace
content:
application/json:
schema:
$ref: '#/components/schemas/V3ErrorResponse'
example:
status: error
message: >-
You do not have permission to update agent:
3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42
error_details:
organizationId: Agent is outside the caller scope
'404':
$ref: '#/components/responses/V3NotFound'
'422':
$ref: '#/components/responses/V3ValidationError'
components:
parameters:
V3AgentId:
name: agent_id
in: path
required: true
description: Unique identifier of the AI agent (`ai_agent_id`).
schema:
type: string
title: Agent Id
schemas:
UpdateAIAgentV3Request:
allOf:
- $ref: '#/components/schemas/V3AgentCallSettings'
- type: object
properties:
agent_name:
anyOf:
- type: string
minLength: 2
maxLength: 200
- type: 'null'
title: Agent Name
description: >-
New name for the agent, 2–200 characters. Omit it to keep the
current name.
llm:
anyOf:
- $ref: '#/components/schemas/V3LlmConfig'
- type: 'null'
description: >-
Changes to the language model configuration. Omitted fields keep
their stored values. Send `llm_id` to change the model;
`model_provider`, `model_name` and `model_display_name` return
`400`.
stt:
anyOf:
- $ref: '#/components/schemas/V3SttConfig'
- type: 'null'
description: >-
Changes to the speech-to-text configuration. Omitted fields keep
their stored values. Send `provider_id` and `model_id` together
to change the model.
tts:
anyOf:
- $ref: '#/components/schemas/V3TtsConfig'
- type: 'null'
description: >-
Changes to the text-to-speech configuration. Omitted fields keep
their stored values. Send `provider_id` and `voice_id` together
to change the voice.
agent_status:
anyOf:
- type: string
enum:
- ACTIVE
- INACTIVE
- type: 'null'
title: Agent Status
description: New lifecycle status. Omit it to keep the current status.
type: object
title: UpdateAIAgentV3Request
description: >-
Every field is optional. Only the fields present in the body are
applied; the rest keep their stored value.
V3ApiResponseAIAgent:
type: object
title: ApiResponse
description: >-
Standard v3 envelope. `error_details` is present only on failures; null
fields are omitted.
properties:
status:
type: string
enum:
- success
- error
title: Status
description: 'Outcome of the request: `success` or `error`, in lowercase.'
message:
type: string
title: Message
description: Human-readable message about the result.
data:
$ref: '#/components/schemas/AIAgentV3Response'
description: The agent. Omitted on errors.
error_details:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Error Details
description: >-
Field path to message, for validation failures. Omitted when there
are none.
V3ErrorResponse:
type: object
title: ErrorResponse
properties:
status:
type: string
enum:
- error
title: Status
description: 'Outcome of the request: `success` or `error`, in lowercase.'
message:
type: string
title: Message
description: Human-readable message about the result.
error_details:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Error Details
description: >-
Field path to message, for validation failures. Omitted when there
are none.
V3AgentCallSettings:
type: object
title: AgentCallSettings
description: >-
Call-behaviour settings shared by the create request, the update request
and the agent response.
properties:
language_code:
anyOf:
- type: string
- type: 'null'
title: Language Code
description: BCP-47 language code for the agent, for example `en-US`.
timezone:
anyOf:
- type: string
- type: 'null'
title: Timezone
description: >-
Canonical IANA time zone the agent reads its clock in, e.g.
'Asia/Tokyo'. Rejected if it is not a tzdb name: abbreviations
(JST), UTC offsets (+09:00) and city-only strings (Tokyo) are not
accepted. Omitted or null leaves the agent without a timezone; there
is no default.
speech_speed:
anyOf:
- type: number
minimum: 0.5
maximum: 2
- type: 'null'
title: Speech Speed
description: >-
Speaking-rate multiplier for the agent's audio: 1.0 is normal, below
1.0 slower, above 1.0 faster.
default: 1
knowledge_base_id:
anyOf:
- type: string
- type: 'null'
title: Knowledge Base Id
description: Knowledge base the agent retrieves from.
welcome_message:
anyOf:
- type: string
- type: 'null'
title: Welcome Message
description: Custom message the agent speaks when the call begins.
examples:
- Hello! Thanks for calling. How can I help you today?
welcome_message_delay_in_seconds:
anyOf:
- type: number
minimum: 0
maximum: 10
- type: 'null'
title: Welcome Message Delay In Seconds
default: 2
description: >-
Delay in seconds, `0`–`10`, before the agent speaks the welcome
message.
enable_user_interruptions:
anyOf:
- type: boolean
- type: 'null'
title: Enable User Interruptions
default: true
description: Whether the caller can interrupt the agent while it is speaking.
interruption_mode:
anyOf:
- type: string
enum:
- vad
- adaptive
- type: 'null'
title: Interruption Mode
description: Interruption detection strategy. Null when unset.
minimum_speech_duration_for_interruptions:
anyOf:
- type: number
minimum: 0.5
maximum: 15
- type: 'null'
title: Minimum Speech Duration For Interruptions
description: >-
Seconds of speech before an interruption is accepted. Minimum 0.5 on
create; 0.0 is accepted on update.
default: 0.5
minimum_words_before_interruption:
anyOf:
- type: integer
minimum: 0
maximum: 10
- type: 'null'
title: Minimum Words Before Interruption
default: 2
description: >-
Minimum number of words, `0`–`10`, the caller must say before the
agent treats the speech as an interruption. Used when
`enable_user_interruptions` is `true`.
vad_activation_threshold:
anyOf:
- type: number
minimum: 0.1
maximum: 0.9
- type: 'null'
title: Vad Activation Threshold
description: >-
Voice activity detection sensitivity, `0.10`–`0.90`. There is no
service-side default: when unset, the call handler uses its own
per-language default, and the key is omitted from create, get and
update responses. On update, omitting the key keeps the stored
value.
wait_time_before_detecting_end_of_speech:
anyOf:
- type: number
maximum: 15
minimum: 0
- type: 'null'
title: Wait Time Before Detecting End Of Speech
description: >-
Seconds of silence before the caller's turn is treated as finished.
**Flow agents only**: when omitted on create, a flow agent gets
`0.2`. Other agent types ignore the value: create stores nothing and
update keeps whatever was stored.
max_endpointing_delay:
anyOf:
- type: number
maximum: 15
minimum: 0
- type: 'null'
title: Max Endpointing Delay
description: >-
Upper bound, in seconds, on how long end-of-speech detection may
wait. **Flow agents only**: when omitted on create, a flow agent
gets `2.0`. It must be greater than
`wait_time_before_detecting_end_of_speech`, otherwise the request
returns `422`. Other agent types ignore the value.
ambient_sound:
anyOf:
- type: string
enum:
- office
- cafe
- restaurant
- park
- street
- home
- library
- airport
- train_station
- beach
- none
- type: 'null'
title: Ambient Sound
default: none
description: Background sound mixed into the call audio. `none` adds no sound.
ambient_sound_volume:
anyOf:
- type: number
maximum: 2
minimum: 0
- type: 'null'
title: Ambient Sound Volume
default: 1
description: Volume of the ambient sound, `0`–`2`, where `1` is normal volume.
enable_noise_cancellation:
anyOf:
- type: boolean
- type: 'null'
title: Enable Noise Cancellation
default: true
description: >-
Whether to apply noise cancellation to the caller's audio before
speech recognition.
webhook_url:
anyOf:
- type: string
- type: 'null'
title: Webhook Url
description: Receives webhook notifications about call events.
end_call_after_silence_seconds:
anyOf:
- type: integer
minimum: 10
maximum: 30
- type: 'null'
title: End Call After Silence Seconds
default: 10
description: >-
Seconds of caller silence, `10`–`30`, after which the call ends
automatically.
max_call_duration_seconds:
anyOf:
- type: integer
minimum: 30
maximum: 3600
- type: 'null'
title: Max Call Duration Seconds
default: 1800
description: Maximum duration of the call in seconds, `30`–`3600`.
end_call_instruction:
anyOf:
- type: string
- type: 'null'
title: End Call Instruction
description: Instruction given to the LLM governing how and when to end the call.
agent_ended_call_delay_seconds:
anyOf:
- type: number
minimum: 0
maximum: 10
- type: 'null'
title: Agent Ended Call Delay Seconds
default: 2
description: >-
Delay in seconds, `0`–`10`, before the call ends when the agent
decides to end it.
enable_amd:
anyOf:
- type: boolean
- type: 'null'
title: Enable Amd
description: Enable answering-machine detection.
default: false
amd_voicemail_message:
anyOf:
- type: string
- type: 'null'
title: Amd Voicemail Message
description: Played when answering-machine detection identifies a voicemail.
voicemail_detection_timeout_seconds:
anyOf:
- type: integer
minimum: 0
- type: 'null'
title: Voicemail Detection Timeout Seconds
default: 90
description: >-
Seconds to wait for voicemail detection before taking action. Used
when `enable_amd` is `true`.
silence_reminder_enabled:
anyOf:
- type: boolean
- type: 'null'
title: Silence Reminder Enabled
default: false
description: >-
Whether the agent reminds the caller to speak after a period of
silence.
silence_reminder_duration_seconds:
anyOf:
- type: number
maximum: 30
minimum: 10
- type: 'null'
title: Silence Reminder Duration Seconds
default: 10
description: >-
Seconds of silence, `10`–`30`, before the agent reminds the caller
to speak. Used when `silence_reminder_enabled` is `true`.
max_number_of_silence_reminders:
anyOf:
- type: integer
minimum: 1
maximum: 10
- type: 'null'
title: Max Number Of Silence Reminders
default: 3
description: >-
Maximum number of silence reminders, `1`–`10`. Used when
`silence_reminder_enabled` is `true`.
interval_between_silence_reminders_seconds:
anyOf:
- type: number
minimum: 3
maximum: 30
- type: 'null'
title: Interval Between Silence Reminders Seconds
default: 10
description: >-
Seconds between two consecutive silence reminders, `3`–`30`. Used
when `silence_reminder_enabled` is `true`.
dynamic_data_config:
anyOf:
- type: array
items:
$ref: '#/components/schemas/V3DynamicDataConfigItem'
- type: 'null'
title: Dynamic Data Config
description: >-
External HTTP sources the agent calls to fetch data during the
conversation, for example a customer record. See [Dynamic
data](/external_context/dynamic_data).
post_call_analysis:
anyOf:
- type: array
items:
$ref: '#/components/schemas/V3PostCallAnalysisItem'
- type: 'null'
title: Post Call Analysis
description: >-
Analysis items to extract from the call after it ends. The `type` of
each item sets the shape of its result. You can also manage these
items with the [post-call analysis
API](/api-reference/post-call-analysis/get-post-call-analysis-configuration-for-an-agent).
examples:
- - type: string
name: call_summary
description: A short summary of the call.
system_prompt: Summarize the call in two sentences.
examples:
- >-
The caller asked about a late delivery and was given a new
date.
- type: enum
name: customer_sentiment
description: Overall sentiment of the caller.
system_prompt: Classify the caller's overall sentiment.
choices:
- positive
- neutral
- negative
pronunciations:
anyOf:
- type: array
items:
$ref: '#/components/schemas/V3Pronunciation'
- type: 'null'
title: Pronunciations
description: >-
Pronunciation overrides: the agent speaks each `term` as its
`replacement`. Applied to `simple` agents only. Entries are stored
as sent, without validation.
V3LlmConfig:
type: object
title: LlmConfig
description: >-
LLM selection. On v3 requests this is a reference (`llm_id` +
`llm_type`, plus `system_prompt` for simple agents); the remaining
fields are resolved from the model catalog and returned on reads.
properties:
llm_id:
anyOf:
- type: string
- type: 'null'
title: Llm Id
description: >-
Id of an entry in the LLM model catalog. Required on create for
`simple` agents. For `flow` agents the flow-default id lives at
`graph_data.agentDefaults.llm.llm_id` instead.
llm_type:
type: string
enum:
- simple
- agentic
- flow
title: Llm Type
description: >-
Required on create. `agentic` is rejected on create (existing
agentic agents remain updatable).
system_prompt:
anyOf:
- type: string
- type: 'null'
title: System Prompt
description: >-
The base prompt that defines the agent's behavior and role. Used by
`simple` agents; flow agents carry their prompts inside
`graph_data`.
examples:
- >-
You are a helpful support assistant for Acme. Answer briefly and
politely.
graph_data:
anyOf:
- type: object
- type: 'null'
title: Graph Data
description: >-
Conversation graph for `flow` agents: `entryNodeId`, `nodes`,
`edges`, `variables`, `globalNodeIds`, `agentDefaults`, `language`.
The server fills provider/model/voice names into the graph from the
catalogs before validating it.
tools:
anyOf:
- type: array
items:
additionalProperties:
type: string
type: object
- type: 'null'
title: Tools
description: >-
List of tools or functions available to the LLM for external
interactions. Each entry is a map of string keys to string values.
Tools also have their own APIs: [Built-in
tools](/api-reference/built-in-tools/list-built-in-tools) and
[Custom tools](/api-reference/custom-tools/list-custom-tools).
required_dynamic_data:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Required Dynamic Data
description: List of dynamic data fields the LLM requires for operation.
examples:
- - customer_name
- order_id
llm_name:
anyOf:
- type: string
- type: 'null'
title: Llm Name
description: Resolved from the catalog; read-only in practice.
llm_description:
anyOf:
- type: string
- type: 'null'
title: Llm Description
description: Resolved from the catalog.
model_provider:
anyOf:
- type: string
- type: 'null'
title: Model Provider
description: >-
Resolved from the catalog, e.g. `openai`, `anthropic`, `verbex`,
`openai_compatible`.
model_name:
anyOf:
- type: string
- type: 'null'
title: Model Name
description: Resolved from the catalog, e.g. `gpt-4o-mini`.
model_display_name:
anyOf:
- type: string
- type: 'null'
title: Model Display Name
description: Resolved from the catalog.
model_temperature:
anyOf:
- type: number
- type: 'null'
title: Model Temperature
description: >-
The agent's own sampling temperature. On create, an omitted value
takes the catalog model's temperature; a sent value, `0` included,
is stored as is. On update, an omitted value keeps the stored one,
even when `llm_id` changes. The service enforces no bounds; the
console allows `0`–`2`.
max_tokens:
anyOf:
- type: integer
- type: 'null'
title: Max Tokens
description: Filled from the LLM model catalog whenever the model is resolved.
V3SttConfig:
type: object
title: SttConfig
description: >-
Speech-to-text selection. v3 requests send `provider_id` + `model_id`;
`provider` and `model` are the resolved names and are returned on reads.
properties:
provider_id:
anyOf:
- type: string
- type: 'null'
title: Provider Id
description: >-
Id of an entry in the STT provider catalog (`GET
/v3/stt/providers`).
model_id:
anyOf:
- type: string
- type: 'null'
title: Model Id
description: >-
Id of a model offered by that provider. Required on create for
non-flow agents.
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
description: >-
Resolved provider name, e.g. `deepgram`. v2 input field; on v3 it is
filled in by the server.
model:
anyOf:
- type: string
- type: 'null'
title: Model
description: Resolved model name, e.g. `nova-2-phonecall`.
language:
anyOf:
- type: string
- type: 'null'
title: Language
description: BCP-47 language code for recognition.
context_prompt:
anyOf:
- type: string
- type: 'null'
title: Context Prompt
description: Context biasing prompt. Honored only by providers that support it.
bias_prompt:
anyOf:
- type: string
- type: 'null'
title: Bias Prompt
description: >-
Context biasing instruction. Honored only by providers that support
it.
hotwords:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Hotwords
description: >-
Terms to bias recognition toward. Honored only by providers that
support it.
configuration:
anyOf:
- type: string
- type: 'null'
title: Configuration
description: Additional provider-specific configuration.
V3TtsConfig:
type: object
title: TtsConfig
description: >-
Text-to-speech selection. v3 requests send `provider_id` + `voice_id`;
`provider`, `voice_name` and `model_name` are the resolved names and are
returned on reads.
properties:
provider_id:
anyOf:
- type: string
- type: 'null'
title: Provider Id
description: >-
Id of an entry in the TTS provider catalog (`GET
/v3/tts/providers`).
voice_id:
anyOf:
- type: string
- type: 'null'
title: Voice Id
description: >-
Id of a voice offered by that provider. Required on create for
non-flow agents. A voice is listed once per language it supports, so
the same `voice_id` can appear under several language codes.
provider:
anyOf:
- type: string
- type: 'null'
title: Provider
description: Resolved provider name, e.g. `elevenlabs`.
voice_name:
anyOf:
- type: string
- type: 'null'
title: Voice Name
description: Resolved voice name.
model_name:
anyOf:
- type: string
- type: 'null'
title: Model Name
description: >-
Resolved synthesis model name. On this catalog the model hangs off
the individual voice, not the provider.
voice_temperature:
anyOf:
- type: number
maximum: 2
minimum: 0
- type: 'null'
title: Voice Temperature
description: >-
Controls the randomness in voice generation, `0`–`2`. Lower values
produce more consistent output, higher values add more variation.
default: 0.2
language:
anyOf:
- type: string
- type: 'null'
title: Language
description: BCP-47 language code for synthesis.
AIAgentV3Response:
allOf:
- $ref: '#/components/schemas/V3AgentCallSettings'
- type: object
properties:
ai_agent_id:
type: string
title: Ai Agent Id
description: Unique identifier for the AI agent.
agent_name:
type: string
title: Agent Name
description: Name of the agent.
agent_status:
type: string
enum:
- ACTIVE
- INACTIVE
- DELETED
title: Agent Status
description: Lifecycle status of the agent.
llm:
anyOf:
- $ref: '#/components/schemas/V3LlmConfig'
- type: 'null'
description: >-
Language model configuration, with the names resolved from the
catalog. For a `flow` agent, `llm_id` and the model fields come
from the flow-default model in
`graph_data.agentDefaults.llm.llm_id`.
stt:
anyOf:
- $ref: '#/components/schemas/V3SttConfig'
- type: 'null'
description: >-
Speech-to-text configuration, with the names resolved from the
catalog. Not stored for a `flow` agent: omitted on get, `null`
in list items.
tts:
anyOf:
- $ref: '#/components/schemas/V3TtsConfig'
- type: 'null'
description: >-
Text-to-speech configuration, with the names resolved from the
catalog. Not stored for a `flow` agent: omitted on get, `null`
in list items.
created_by_user_id:
anyOf:
- type: string
- type: 'null'
title: Created By User Id
description: Id of the user who created the agent.
organization_id:
anyOf:
- type: string
- type: 'null'
title: Organization Id
description: Id of the organization that owns the agent.
workspace_id:
anyOf:
- type: string
- type: 'null'
title: Workspace Id
description: >-
Id of the workspace the agent belongs to. Null for an agent with
no workspace.
agent_owner_id:
anyOf:
- type: string
- type: 'null'
title: Agent Owner Id
description: >-
Equal to `created_by_user_id` for an agent with no workspace,
otherwise the workspace owner. Not set for a `flow` agent.
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
description: When the agent was created.
modified_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Modified At
description: When the agent was last modified.
current_version:
anyOf:
- type: integer
- type: 'null'
title: Current Version
description: Latest version number of the agent.
current_version_name:
anyOf:
- type: string
- type: 'null'
title: Current Version Name
description: Label of the current version; null when unnamed.
operation_type:
anyOf:
- type: string
enum:
- CREATE
- CREATE_FLOW_BUILDER
- UPDATE
- UPDATE_FLOW_BUILDER
- UPDATE_AGENTIC
- DEACTIVATE
- GET
- type: 'null'
title: Operation Type
description: Which operation produced this body.
required:
- ai_agent_id
type: object
title: AIAgentV3Response
description: >-
Agent body returned by create, get, update and delete. Null fields are
omitted.
V3DynamicDataConfigItem:
type: object
title: DynamicDataConfigItem
description: An external HTTP call the agent makes to fetch data during a call.
properties:
name:
anyOf:
- type: string
- type: 'null'
title: Name
examples:
- customer_data
description: Name of the data source. Legacy field, kept for older agents.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: What the data source provides. Legacy field, kept for older agents.
url:
anyOf:
- type: string
- type: 'null'
title: Url
examples:
- https://api.example.com/customer-data
description: >-
The endpoint URL from which to fetch dynamic data during the
conversation.
method:
anyOf:
- type: string
- type: 'null'
title: Method
default: GET
description: >-
The HTTP method to use when calling the endpoint, for example `GET`,
`POST` or `PUT`.
timeout:
anyOf:
- type: integer
minimum: 1000
- type: 'null'
title: Timeout
description: >-
Maximum time in milliseconds to wait for the endpoint response
before timing out. Minimum `1000`.
default: 2000
headers:
anyOf:
- additionalProperties:
type: string
type: object
- type: 'null'
title: Headers
description: >-
HTTP headers to include in the request, for example an authorization
token or the content type.
examples:
- Authorization: Bearer
body:
anyOf:
- type: object
- type: 'null'
title: Body
description: Request body to send to the endpoint, for `POST` and `PUT` requests.
query:
anyOf:
- type: object
- type: 'null'
title: Query
description: URL query parameters to include in the request, for `GET` requests.
cache:
anyOf:
- type: boolean
- type: 'null'
title: Cache
default: true
description: >-
Whether to cache the response data, to avoid repeated calls for the
same information.
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
description: >-
Whether the data source is enabled. Legacy field, kept for older
agents.
config:
anyOf:
- type: string
- type: 'null'
title: Config
description: >-
Configuration payload as a JSON string. Legacy field, kept for older
agents.
response_data:
anyOf:
- type: array
items:
$ref: '#/components/schemas/V3ResponseDataItem'
- type: 'null'
title: Response Data
description: >-
Fields to extract from the endpoint response. Each entry names a
value and the JSONPath that selects it.
V3PostCallAnalysisItem:
type: object
title: PostCallAnalysisItem
description: >-
A legacy analysis item embedded on the agent. Distinct from the
post-call analysis configuration API at
`/v2/ai-agents/{ai_agent_id}/postcall-analysis`.
properties:
type:
anyOf:
- type: string
enum:
- string
- enum
- boolean
- number
- type: 'null'
title: Type
description: >-
Shape of the result. `string` returns a text string, `enum` returns
one value from `choices`, `boolean` returns `true` or `false`, and
`number` returns a numeric value.
name:
anyOf:
- type: string
- type: 'null'
title: Name
examples:
- call_summary
description: Unique identifier for this analysis item.
description:
anyOf:
- type: string
- type: 'null'
title: Description
description: >-
Detailed explanation of what this analysis item measures or
determines from the call.
system_prompt:
anyOf:
- type: string
- type: 'null'
title: System Prompt
description: >-
Instructions for the AI on how to analyze the call and produce this
item.
examples:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Examples
description: >-
Sample responses that guide the AI toward the expected answer. For
`string` items.
choices:
anyOf:
- items:
type: string
type: array
- type: 'null'
title: Choices
description: The complete list of values the item can return. For `enum` items.
enabled:
anyOf:
- type: boolean
- type: 'null'
title: Enabled
description: Whether this analysis item is enabled.
dynamic_data_config:
anyOf:
- $ref: '#/components/schemas/V3DynamicDataConfigItem'
- type: 'null'
title: Dynamic Data Config
description: Dynamic data source the analysis can use.
V3Pronunciation:
type: object
title: Pronunciation
description: >-
Pronunciation override applied by the voice pipeline. Simple agents
only.
properties:
id:
anyOf:
- type: string
- type: 'null'
title: Id
description: Client-supplied identifier for the entry.
examples:
- r1
term:
anyOf:
- type: string
- type: 'null'
title: Term
examples:
- API
description: Word or phrase to override, as it appears in the agent's text.
replacement:
anyOf:
- type: string
- type: 'null'
title: Replacement
examples:
- ay pee eye
description: What the agent speaks instead of `term`.
V3ResponseDataItem:
type: object
title: ResponseDataItem
properties:
name:
type: string
title: Name
description: Unique name for this extracted field.
examples:
- customer_name
data:
type: string
title: Data
description: JSONPath expression selecting the value.
examples:
- $.customer.name
context:
anyOf:
- type: string
- type: 'null'
title: Context
description: >-
Additional context about this field, to help the agent understand
and use the value.
responses:
V3NotFound:
description: No active agent with that id
content:
application/json:
schema:
$ref: '#/components/schemas/V3ErrorResponse'
example:
status: error
message: 'Agent not found with ID: 3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42'
V3ValidationError:
description: >-
The request body failed validation, or a referenced catalog record was
missing, inactive or incompatible
content:
application/json:
schema:
$ref: '#/components/schemas/V3ErrorResponse'
examples:
bean_validation:
summary: Field out of range (keys are Java property names)
value:
status: error
message: Validation failed
error_details:
vadActivationThreshold: VAD activation threshold cannot exceed 0.90
wrong_type:
summary: Wrong field type (keys are JSON names)
value:
status: error
message: Invalid field type in request body
error_details:
vad_activation_threshold: 'Invalid value ''high''. Expected type: Double'
inactive_model:
summary: Referenced LLM model is not active
value:
status: error
message: LLM model validation failed
error_details:
llm.llm_id: 'LLM model is not active. Current status: INACTIVE'
unknown_model:
summary: Referenced LLM model does not exist
value:
status: error
message: LLM model lookup failed
error_details:
llm.llm_id: Referenced LLM model was not found
stt_model_not_on_provider:
summary: STT model is not offered by that provider
value:
status: error
message: STT validation failed
error_details:
data.stt.model_id: invalid model id for provider 6a5c45808d2d94e9d0e255d3
endpointing:
summary: 'Flow agent: `max_endpointing_delay` not above the wait time'
value:
status: error
message: Agent validation failed
error_details:
max_endpointing_delay: >-
max_endpointing_delay (0.2) must be greater than
wait_time_before_detecting_end_of_speech (0.5)
flow_invalid_voice:
summary: 'Flow agent: graph voice not offered by that provider'
value:
status: error
message: Agent validation failed for flow builder graph data
error_details:
llm.graph_data.agentDefaults.tts.voice_id: invalid voice_id for provider 6a5c079f814b8ed08b15172b
flow_graph_without_type:
summary: 'Flow agent: `graph_data` sent without `llm.llm_type`'
value:
status: error
message: Agent validation failed
error_details:
llm.llmType: LLM type is required when updating graph data
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.