> ## 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.
# Delete AI Agent
> Delete an agent. This is a soft delete, and the response carries the agent.
**The v2 equivalent, [`DELETE /v2/ai-agents/{agent_id}`](/api-reference/ai-agents-v2/delete-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.
## Soft delete
The agent record is kept and its status moves to `INACTIVE`. After the delete:
- [Get AI Agent](/api-reference/ai-agents-v3/get-ai-agent) returns `404` for the agent.
- [List AI Agents](/api-reference/ai-agents-v3/list-ai-agents) returns it only when you filter on `agent_status=INACTIVE`.
The caller must be in the agent's scope. A workspace-scoped key must match the agent's workspace; otherwise the key's organization must match the agent's organization.
## 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`.
```json
{
"status": "success",
"message": "Agent deactivated successfully",
"data": {
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"operation_type": "DEACTIVATE"
}
}
```
`data` is the agent as it was **before** deactivation, so `agent_status` still reads `ACTIVE`.
## Status codes
| Code | When |
| --- | --- |
| `200` | Deleted. |
| `403` | The agent belongs to another organization or workspace. |
| `404` | No such agent. |
## OpenAPI
````yaml /api-reference/openapi.json delete /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}:
delete:
tags:
- AI Agents v3
summary: Delete AI Agent
description: >-
Delete an agent. This is a soft delete, and the response carries the
agent.
**The v2 equivalent, [`DELETE
/v2/ai-agents/{agent_id}`](/api-reference/ai-agents-v2/delete-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.
## Soft delete
The agent record is kept and its status moves to `INACTIVE`. After the
delete:
- [Get AI Agent](/api-reference/ai-agents-v3/get-ai-agent) returns `404`
for the agent.
- [List AI Agents](/api-reference/ai-agents-v3/list-ai-agents) returns
it only when you filter on `agent_status=INACTIVE`.
The caller must be in the agent's scope. A workspace-scoped key must
match the agent's workspace; otherwise the key's organization must match
the agent's organization.
## 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`.
```json
{
"status": "success",
"message": "Agent deactivated successfully",
"data": {
"ai_agent_id": "3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42",
"agent_name": "Customer Support Agent",
"agent_status": "ACTIVE",
"operation_type": "DEACTIVATE"
}
}
```
`data` is the agent as it was **before** deactivation, so `agent_status`
still reads `ACTIVE`.
## Status codes
| Code | When |
| --- | --- |
| `200` | Deleted. |
| `403` | The agent belongs to another organization or workspace. |
| `404` | No such agent. |
operationId: delete_ai_agent_v3
parameters:
- $ref: '#/components/parameters/V3AgentId'
responses:
'200':
description: Agent deleted
content:
application/json:
schema:
$ref: '#/components/schemas/V3ApiResponseAIAgent'
examples:
simple:
summary: Simple agent
value:
status: success
message: Agent deactivated 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: DEACTIVATE
flow:
summary: Flow agent
value:
status: success
message: Agent deactivated 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: cgSgspJ2msm6clMCkdW9
provider: elevenlabs
voice: cgSgspJ2msm6clMCkdW9
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-15T09:41:03.220Z'
current_version: 1
operation_type: DEACTIVATE
'400':
$ref: '#/components/responses/V3BadRequest'
'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 delete agent:
3f6c2a1e-8b4d-4c9a-9e2f-7d1b5a6c0e42
error_details:
organizationId: Agent is outside the caller scope
'404':
$ref: '#/components/responses/V3NotFound'
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:
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.
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.
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.
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:
V3BadRequest:
description: Malformed request or missing tenant scope
content:
application/json:
schema:
$ref: '#/components/schemas/V3ErrorResponse'
example:
status: error
message: Both workspaceId and organizationId are missing
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'
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.