curl --request PUT \
  --url https://api.example.com/v3/ai-agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "Tier-1 Support Agent"
}
'

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

AI Agents v3

Update AI Agent

Update an agent and return the full updated agent.

The v2 equivalent, PUT /v2/ai-agents/{agent_id}, is deprecated and stops working on November 30, 2026. This is the v3 endpoint. Migrate from v2 to v3 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:

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:

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

PUT

ai-agents

{agent_id}

curl --request PUT \
  --url https://api.example.com/v3/ai-agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_name": "Tier-1 Support Agent"
}
'

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

Path Parameters

agent_id

string

required

Unique identifier of the AI agent (ai_agent_id).

Body

application/json

Every field is optional. Only the fields present in the body are applied; the rest keep their stored value.

language_code

string | null

BCP-47 language code for the agent, for example en-US.

timezone

string | null

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

number | null

default:1

Speaking-rate multiplier for the agent's audio: 1.0 is normal, below 1.0 slower, above 1.0 faster.

Required range: 0.5 <= x <= 2

knowledge_base_id

string | null

Knowledge base the agent retrieves from.

welcome_message

string | null

Custom message the agent speaks when the call begins.

Example:

"Hello! Thanks for calling. How can I help you today?"

welcome_message_delay_in_seconds

number | null

default:2

Delay in seconds, 0–10, before the agent speaks the welcome message.

Required range: 0 <= x <= 10

enable_user_interruptions

boolean | null

default:true

Whether the caller can interrupt the agent while it is speaking.

interruption_mode

enum<string> | null

Interruption detection strategy. Null when unset.

Available options:

vad,

adaptive

minimum_speech_duration_for_interruptions

number | null

default:0.5

Seconds of speech before an interruption is accepted. Minimum 0.5 on create; 0.0 is accepted on update.

Required range: 0.5 <= x <= 15

minimum_words_before_interruption

integer | null

default:2

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.

Required range: 0 <= x <= 10

vad_activation_threshold

number | null

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.

Required range: 0.1 <= x <= 0.9

wait_time_before_detecting_end_of_speech

number | null

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.

Required range: 0 <= x <= 15

max_endpointing_delay

number | null

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.

Required range: 0 <= x <= 15

ambient_sound

enum<string> | null

default:none

Background sound mixed into the call audio. none adds no sound.

Available options:

office,

cafe,

restaurant,

park,

street,

home,

library,

airport,

train_station,

beach,

none

ambient_sound_volume

number | null

default:1

Volume of the ambient sound, 0–2, where 1 is normal volume.

Required range: 0 <= x <= 2

enable_noise_cancellation

boolean | null

default:true

Whether to apply noise cancellation to the caller's audio before speech recognition.

webhook_url

string | null

Receives webhook notifications about call events.

end_call_after_silence_seconds

integer | null

default:10

Seconds of caller silence, 10–30, after which the call ends automatically.

Required range: 10 <= x <= 30

max_call_duration_seconds

integer | null

default:1800

Maximum duration of the call in seconds, 30–3600.

Required range: 30 <= x <= 3600

end_call_instruction

string | null

Instruction given to the LLM governing how and when to end the call.

agent_ended_call_delay_seconds

number | null

default:2

Delay in seconds, 0–10, before the call ends when the agent decides to end it.

Required range: 0 <= x <= 10

enable_amd

boolean | null

default:false

Enable answering-machine detection.

amd_voicemail_message

string | null

Played when answering-machine detection identifies a voicemail.

voicemail_detection_timeout_seconds

integer | null

default:90

Seconds to wait for voicemail detection before taking action. Used when enable_amd is true.

Required range: x >= 0

silence_reminder_enabled

boolean | null

default:false

Whether the agent reminds the caller to speak after a period of silence.

silence_reminder_duration_seconds

number | null

default:10

Seconds of silence, 10–30, before the agent reminds the caller to speak. Used when silence_reminder_enabled is true.

Required range: 10 <= x <= 30

max_number_of_silence_reminders

integer | null

default:3

Maximum number of silence reminders, 1–10. Used when silence_reminder_enabled is true.

Required range: 1 <= x <= 10

interval_between_silence_reminders_seconds

number | null

default:10

Seconds between two consecutive silence reminders, 3–30. Used when silence_reminder_enabled is true.

Required range: 3 <= x <= 30

dynamic_data_config

DynamicDataConfigItem · object[] | null

External HTTP sources the agent calls to fetch data during the conversation, for example a customer record. See Dynamic data.

Show child attributes

post_call_analysis

PostCallAnalysisItem · object[] | null

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.

Show child attributes

Example:

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

Pronunciation · object[] | null

Pronunciation overrides: the agent speaks each term as its replacement. Applied to simple agents only. Entries are stored as sent, without validation.

Show child attributes

agent_name

string | null

New name for the agent, 2–200 characters. Omit it to keep the current name.

Required string length: 2 - 200

llm

LlmConfig · object | null

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.

Show child attributes

stt

SttConfig · object | null

Changes to the speech-to-text configuration. Omitted fields keep their stored values. Send provider_id and model_id together to change the model.

Show child attributes

tts

TtsConfig · object | null

Changes to the text-to-speech configuration. Omitted fields keep their stored values. Send provider_id and voice_id together to change the voice.

Show child attributes

agent_status

enum<string> | null

New lifecycle status. Omit it to keep the current status.

Available options:

ACTIVE,

INACTIVE

Response

Agent updated

Standard v3 envelope. error_details is present only on failures; null fields are omitted.

status

enum<string>

Outcome of the request: success or error, in lowercase.

Available options:

success,

error

message

string

Human-readable message about the result.

data

AIAgentV3Response · object

The agent. Omitted on errors.

Show child attributes

error_details

Error Details · object | null

Field path to message, for validation failures. Omitted when there are none.

Show child attributes

API Reference

AI Agents v3

AI Agents v2

LLM Models

Speech Providers

Built-in Tools

Custom Tools

Calls

Call Recording

Post-call Analysis

Phone Numbers

Knowledge Bases

Prompt Generation

Public Sharing

Webhook Subscriptions

API Keys

Update AI Agent

Partial updates

Changing the LLM, STT model or voice

Flow agents

Rejected LLM fields

Field notes

Versioning

Response envelope

Status codes

Path Parameters

Body

Response