--- title: "Patches An Agent Settings" method: PATCH path: "/v1/convai/agents/{agent_id}" tags: ["Agents Platform"] --- # Patches An Agent Settings `PATCH /v1/convai/agents/{agent_id}` Patches an Agent settings ## Path parameters - `agent_id` string, required — The id of an agent. This is returned on agent creation. ## Query parameters - `enable_versioning_if_not_enabled` boolean — Deprecated: all agents are versioned. This parameter is ignored. - `branch_id` string, nullable — The ID of the branch to use ## Headers - `xi-api-key` string, nullable — Your API key. This is required by most endpoints to access our API programmatically. You can view your xi-api-key using the 'Profile' tab on the website. ## Request body - BodyPatchesAnAgentSettingsV1ConvaiAgentsAgentIdPatch - `conversation_config` object, nullable — Conversation configuration for an agent - `platform_settings` object, nullable — Platform settings for the agent are all settings that aren't related to the conversation orchestration and content. - `workflow` AgentWorkflowRequestModel - `edges` object - `nodes` object - `prevent_subagent_loops` boolean — Whether to prevent loops in the workflow execution. - `name` string, nullable — A name to make the agent easier to find - `tags` string[], nullable — Tags to help classify and filter the agent - `version_description` string, nullable — Description for this version when publishing changes (only applicable for versioned agents) ## Response `200` Successful Response - GetAgentResponseModel - `agent_id` string, required — The ID of the agent - `name` string, required — The name of the agent - `conversation_config` ConversationalConfigAPIModelOutput, required - `asr` ASRConversationalConfig - `quality` 'high' - `provider` 'elevenlabs' | 'scribe_realtime' - `user_input_audio_format` 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'pcm_48000' | 'ulaw_8000' - `keywords` string[] — Keywords to boost prediction probability for - `turn` TurnConfig - `turn_timeout` number — Maximum wait time for the user's reply before re-engaging the user - `initial_wait_time` number, nullable — How long the agent will wait for the user to start the conversation if the first message is empty. If not set, uses the regular turn_timeout. - `silence_end_call_timeout` number — Maximum wait time since the user last spoke before terminating the call - `mode` 'silence' | 'turn' - `turn_eagerness` 'patient' | 'normal' | 'eager' — Agent's eagerness to respond. Higher values make agent wait for higher turn probability. - `spelling_patience` 'auto' | 'off' — Controls if the agent should be more patient when user is spelling numbers and named entities. - `speculative_turn` boolean — When enabled, starts generating LLM responses during silence before full turn confidence is reached, reducing perceived latency. May increase LLM costs. - `retranscribe_on_turn_timeout` boolean — When enabled, if VAD detects no speech, attempts to re-transcribe accumulated audio at turn timeout. Disables silence discount billing for affected turns. - `turn_model` 'turn_v2' | 'turn_v3' — Version of the turn detection model to use. - `interruption_ignore_terms` string[] — List of terms that should not trigger an interruption when spoken by the user (e.g. 'gotcha', 'understood'). Uses case-insensitive exact matching. - `interruption_ignore_term_languages` string[] — Language codes for which preset ignore-term categories have been activated. Stored explicitly so display is not inferred from term overlap. - `transcribe_on_disabled_interruptions` boolean — When interruptions are disabled, still transcribe what the user says so it can carry into the next turn. When off, user speech during a non-interruptible turn is ignored and won't trigger a turn. - `soft_timeout_config` SoftTimeoutConfig — Configuration for soft timeout functionality during LLM response generation. - `timeout_seconds` number — Time in seconds before showing the predefined message while waiting for LLM response. Set to -1 to disable. - `message` string — Message to show when the first soft timeout is reached while waiting for LLM response. Supports dynamic variables (e.g., {{system__time}}, {{custom_variable}}). - `additional_soft_timeout_messages` string[] — Extra static filler messages for subsequent soft timeouts in the same LLM generation. The first timeout uses `message`. If fewer messages are configured than `max_soft_timeouts_per_generation`, the last configured message is repeated; otherwise a built-in filler is used. - `use_llm_generated_message` boolean — If enabled, the soft timeout message will be generated dynamically instead of using the static message. - `randomize_fillers` boolean — If enabled, shuffle the order of static soft timeout messages once at the start of each turn. Only applies when use_llm_generated_message is false. - `max_soft_timeouts_per_generation` integer — Maximum filler messages while waiting for a single LLM response. Fires every timeout_seconds until the LLM streams content or this limit is reached. - `llm_generated_message_prompt_override` string, nullable — Custom prompt for generating the soft timeout filler message when use_llm_generated_message is enabled. Recent conversation context is provided as a separate user message. If not set, the default prompt will be used. Supports dynamic variables (e.g., {{system__time}}, {{custom_variable}}). - `tts` TTSConversationalConfigOutput - `model_id` 'eleven_turbo_v2' | 'eleven_turbo_v2_5' | 'eleven_flash_v2' | 'eleven_flash_v2_5' | 'eleven_multilingual_v2' | 'eleven_v3_conversational' - `voice_id` string — The voice ID to use for TTS - `supported_voices` SupportedVoice[] — Additional supported voices for the agent - `label` string, required - `voice_id` string, required - `description` string, nullable - `language` string, nullable - `model_family` 'turbo' | 'flash' | 'multilingual' | 'v3_conversational' - `optimize_streaming_latency` 0 | 1 | 2 | 3 | 4 - `stability` number, nullable - `speed` number, nullable - `similarity_boost` number, nullable - `expressive_mode` boolean — When enabled, applies expressive audio tags prompt. Automatically disabled for non-v3 models. - `suggested_audio_tags` SuggestedAudioTag[] — Suggested audio tags to boost expressive speech (for eleven_v3 and eleven_v3_conversational models). The agent can still use other tags not listed here. - `tag` string, required — Audio tag to use (for best performance, 1-2 words, e.g., 'happy', 'excited') - `description` string, nullable — Optional description of when to use this tag - `agent_output_audio_format` 'pcm_8000' | 'pcm_16000' | 'pcm_22050' | 'pcm_24000' | 'pcm_44100' | 'pcm_48000' | 'ulaw_8000' - `optimize_streaming_latency` 0 | 1 | 2 | 3 | 4 - `stability` number — The stability of generated speech - `speed` number — The speed of generated speech - `similarity_boost` number — The similarity boost for generated speech - `text_normalisation_type` 'system_prompt' | 'elevenlabs' — Method for converting numbers to words before sending to TTS - `pronunciation_dictionary_locators` PydanticPronunciationDictionaryVersionLocator[] — The pronunciation dictionary locators - `pronunciation_dictionary_id` string, required — The ID of the pronunciation dictionary - `version_id` string, nullable, required — The ID of the version of the pronunciation dictionary - `enable_phoneme_tags` boolean — Opt-in to SSML phoneme tag handling for V3 models. When enabled, phoneme tags (inline and from pronunciation dictionaries) are parsed into inline IPA before being sent to the model. - `conversation` ConversationConfigOutput - `text_only` boolean — If enabled audio will not be processed and only text will be used, use to avoid audio pricing. - `max_duration_seconds` integer — The maximum duration of a conversation in seconds - `client_events` ClientEvent[] — The events that will be sent to the client - `file_input` FileInputConfig - `enabled` boolean — When enabled, users may attach images or PDFs in chat when the LLM supports multimodal input. - `max_files_in_memory` integer — Number of most-recent files kept in memory during a conversation. Older files are summarized and their bytes freed. - `max_files_per_conversation` integer — Total files a user can upload in one conversation. Uploads are billed per file. Use -1 for no limit, or a value >= max_files_in_memory. - `monitoring_enabled` boolean — Enable real-time monitoring of conversations via WebSocket - `monitoring_events` ClientEvent[] — The events that will be sent to monitoring connections. - `background_sound` BackgroundSoundConfig - `source_type` 'preset' — The type of background sound source. - `source_id` 'office2' | 'office1' | 'restaurant' | 'city' | 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4' — Predefined background sound preset identifiers. - `volume` number — Volume level for background sound (0.01 to 1.0). - `crossfade_loop` boolean — Apply a crossfade at the loop boundary to avoid audible pops when the sound loops. - `source_attribution` boolean — When enabled and knowledge base content is present, the LLM is instructed to report which sources it used. - `language_presets` object — Language presets for conversations - `vad` VADConfig - `background_voice_detection` boolean — Whether to use background voice filtering - `agent` AgentConfigAPIModelOutput - `first_message` string — If non-empty, the first message the agent will say. If empty, the agent waits for the user to start the discussion. - `language` string — Language of the agent - used for ASR and TTS - `hinglish_mode` boolean — When enabled and language is Hindi, the agent will respond in Hinglish - `dynamic_variables` DynamicVariablesConfig - `dynamic_variable_placeholders` object — A dictionary of dynamic variable placeholders and their values - `disable_first_message_interruptions` boolean — If true, the user will not be able to interrupt the agent while the first message is being delivered. - `max_conversation_duration_message` string — If non-empty, the message the agent will send when max conversation duration is reached. - `text_behavior_overrides` object, nullable — Per-channel response behavior overrides for text conversations. Built-in channel defaults apply when unset. - `prompt` PromptAgentAPIModelOutput - `prompt` string — The prompt for the agent - `llm` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.2-chat-latest' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-3.5-turbo' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'claude-sonnet-4-5' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-sonnet-4' | 'claude-haiku-4-5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-sonnet-v1' | 'claude-3-haiku' | 'grok-beta' | 'custom-llm' | 'qwen3-4b' | 'qwen3-30b-a3b' | 'qwen36-35b-a3b' | 'qwen35-397b-a17b' | 'gpt-oss-20b' | 'gpt-oss-120b' | 'glm-45-air-fp8' | 'gemini-2.5-flash-preview-09-2025' | 'gemini-2.5-flash-lite-preview-09-2025' | 'gemini-2.5-flash-preview-05-20' | 'gemini-2.5-flash-preview-04-17' | 'gemini-2.5-flash-lite-preview-06-17' | 'gemini-2.0-flash-lite-001' | 'gemini-2.0-flash-001' | 'gemini-1.5-flash-002' | 'gemini-1.5-flash-001' | 'gemini-1.5-pro-002' | 'gemini-1.5-pro-001' | 'claude-sonnet-4@20250514' | 'claude-sonnet-4-5@20250929' | 'claude-haiku-4-5@20251001' | 'claude-3-7-sonnet@20250219' | 'claude-3-5-sonnet@20240620' | 'claude-3-5-sonnet-v2@20241022' | 'claude-3-haiku@20240307' | 'gpt-5-2025-08-07' | 'gpt-5.1-2025-11-13' | 'gpt-5.2-2025-12-11' | 'gpt-5.4-2026-03-05' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.5-2026-04-23' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'gpt-4o-mini-2024-07-18' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4-0613' | 'gpt-4-0314' | 'gpt-4-turbo-2024-04-09' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-1106' | 'watt-tool-8b' | 'watt-tool-70b' - `reasoning_effort` 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max' - `thinking_budget` integer, nullable — Max number of tokens used for thinking. Use 0 to turn off if supported by the model. - `enable_reasoning_summary` boolean — Enable model reasoning summaries. When disabled, we do not request summaries from provider if possible for faster TTFB. Not ZRM compatible. - `temperature` number, nullable — The temperature for the LLM. Defaults to 0. Set to null to omit the parameter from the LLM request entirely (useful for custom LLMs that reject the temperature field). - `max_tokens` integer — If greater than 0, maximum number of tokens the LLM can predict - `tool_ids` string[] — A list of IDs of tools used by the agent - `built_in_tools` BuiltInToolsOutput - `end_call` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `language_detection` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `transfer_to_agent` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `transfer_to_number` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `skip_turn` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `play_keypad_touch_tone` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `voicemail_detection` SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - `type` 'system' — The type of tool - `name` string, required - `description` string — Description of when the tool should be used and what it does. Leave empty to use the default description that's optimized for the specific tool type. - `response_timeout_secs` integer — The maximum time in seconds to wait for the tool call to complete. - `disable_interruptions` boolean — DEPRECATED: use `interruption_mode` instead. If true, the user will not be able to interrupt the agent while this tool is running. - `interruption_mode` 'allow' | 'disable_during_tool' | 'disable_during_tool_and_turn' - `force_pre_tool_speech` boolean — DEPRECATED: use `pre_tool_speech` instead. If true, the agent will speak before the tool call. - `pre_tool_speech` 'auto' | 'force' | 'off' - `assignments` DynamicVariableAssignment[] — Configuration for extracting values from tool responses and assigning them to dynamic variables - … - `tool_call_sound` 'typing' | 'elevator1' | 'elevator2' | 'elevator3' | 'elevator4', nullable — Predefined tool call sounds; ``None`` means no sound. - `tool_call_sound_behavior` 'auto' | 'always' — Determines how the tool call sound should be played. - `tool_error_handling_mode` 'auto' | 'summarized' | 'passthrough' | 'hide' — Controls how tool errors are processed before being shared with the agent. - `params` union, required - … - `mcp_server_ids` string[] — A list of MCP server ids to be used by the agent - `native_mcp_server_ids` string[] — A list of Native MCP server ids to be used by the agent - `knowledge_base` KnowledgeBaseLocator[] — A list of knowledge bases to be used by the agent - `type` 'file' | 'url' | 'text' | 'folder', required - `name` string, required — The name of the knowledge base - `id` string, required — The ID of the knowledge base - `usage_mode` 'prompt' | 'auto' - `custom_llm` CustomLLM - `url` string, required — The URL of the Chat Completions compatible endpoint - `model_id` string, nullable — The model ID to be used if URL serves multiple models - `api_key` union — The API key for authentication. Either a workspace secret reference {'secret_id': '...'} or an environment variable reference {'env_var_label': '...'}. - ConvAISecretLocator — Used to reference a secret from the agent's secret store. - … - ConvAIEnvVarLocator — Used to reference an environment variable by label. - … - `auth_connection` union — Optional workspace auth connection for authentication. Only auth connections that produce an Authorization Bearer token are supported; Basic auth, mTLS, custom header, and URL secret auth connections are not supported. - AuthConnectionLocator — Used to reference an auth connection from the workspace's auth connection store. - … - EnvironmentAuthConnectionLocator — References an environment variable of type 'auth_connection' by label. At runtime, resolves to the auth connection for the current environment, falling back to the default environment. - … - `request_headers` object — Headers that should be included in the request - `api_version` string, nullable — The API version to use for the request - `api_type` 'chat_completions' | 'responses' | 'websocket' - `ignore_default_personality` boolean, nullable — Whether to remove the default personality lines from the system prompt - `rag` RagConfigOutput - `enabled` boolean - `embedding_model` 'e5_mistral_7b_instruct' | 'multilingual_e5_large_instruct' - `max_vector_distance` number — Maximum vector distance of retrieved chunks. - `max_documents_length` integer — Maximum total length of document chunks retrieved from RAG. - `max_retrieved_rag_chunks_count` integer — Maximum number of RAG document chunks to initially retrieve from the vector store. These are then further filtered by vector distance and total length. - `num_candidates` integer, nullable — Number of candidates evaluated in ANN vector search. Higher number means better results, but higher latency. Minimum recommended value is 100. If disabled, the default value is used. - `query_rewrite_prompt_override` string, nullable — Custom prompt for rewriting user queries before RAG retrieval. The conversation history will be automatically appended at the end. If not set, the default prompt will be used. - `timezone` string, nullable — Timezone for displaying current time in system prompt. If set, the current time will be included in the system prompt using this timezone. Must be a valid timezone name (e.g., 'America/New_York', 'Europe/London', 'UTC'). Recommended for accurate time-aware responses; without this, the agent has no knowledge of the current date/time unless you provide it via dynamic variables or tools, which can lead to incorrect or hallucinated time references. - `backup_llm_config` union — Configuration for backup LLM cascading. Can be disabled, use system defaults, or specify custom order. - BackupLLMDefault - `preference` 'default' - BackupLLMDisabled - `preference` 'disabled' - BackupLLMOverride - `preference` 'override' - `order` LLM[], required - `cascade_timeout_seconds` number — Time in seconds before cascading to backup LLM. Must be between 2 and 15 seconds. - `tools` union[] — A list of tools that the agent can use over the course of the conversation, use tool_ids instead - union — The type of tool - WebhookToolConfigOutput — A webhook tool is a tool that calls an external webhook from our server - … - ClientToolConfigOutput — A client tool is one that sends an event to the user's client to trigger something client side - … - SystemToolConfigOutput — A system tool is a tool that is used to call a system method in the server - … - MCPToolConfigOutput — An MCP tool configuration that can be used to call MCP servers - … - ApiIntegrationWebhookToolConfigOutput - … - SMBToolConfig — SMB tool configuration that wraps SMB tool parameters. - … - `metadata` AgentMetadataResponseModel, required - `created_at_unix_secs` integer, required — The creation time of the agent in unix seconds - `updated_at_unix_secs` integer, required — The last update time of the agent in unix seconds - `platform_settings` AgentPlatformSettingsResponseModel - `evaluation` EvaluationSettingsOutput — Settings to evaluate an agent's performance. Agents are evaluated against a set of criteria, with success being defined as meeting some combination of those criteria. - `criteria` PromptEvaluationCriteria[] — Individual criteria that the agent should be evaluated against - `id` string, required — The unique identifier for the evaluation criteria - `name` string, required - `type` 'prompt' — The type of evaluation criteria - `conversation_goal_prompt` string, required — The prompt that the agent should use to evaluate the conversation - `use_knowledge_base` boolean — When evaluating the prompt, should the agent's knowledge base be used. - `scope` 'conversation' | 'agent' - `llm` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.2-chat-latest' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-3.5-turbo' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'claude-sonnet-4-5' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-sonnet-4' | 'claude-haiku-4-5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-sonnet-v1' | 'claude-3-haiku' | 'grok-beta' | 'custom-llm' | 'qwen3-4b' | 'qwen3-30b-a3b' | 'qwen36-35b-a3b' | 'qwen35-397b-a17b' | 'gpt-oss-20b' | 'gpt-oss-120b' | 'glm-45-air-fp8' | 'gemini-2.5-flash-preview-09-2025' | 'gemini-2.5-flash-lite-preview-09-2025' | 'gemini-2.5-flash-preview-05-20' | 'gemini-2.5-flash-preview-04-17' | 'gemini-2.5-flash-lite-preview-06-17' | 'gemini-2.0-flash-lite-001' | 'gemini-2.0-flash-001' | 'gemini-1.5-flash-002' | 'gemini-1.5-flash-001' | 'gemini-1.5-pro-002' | 'gemini-1.5-pro-001' | 'claude-sonnet-4@20250514' | 'claude-sonnet-4-5@20250929' | 'claude-haiku-4-5@20251001' | 'claude-3-7-sonnet@20250219' | 'claude-3-5-sonnet@20240620' | 'claude-3-5-sonnet-v2@20241022' | 'claude-3-haiku@20240307' | 'gpt-5-2025-08-07' | 'gpt-5.1-2025-11-13' | 'gpt-5.2-2025-12-11' | 'gpt-5.4-2026-03-05' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.5-2026-04-23' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'gpt-4o-mini-2024-07-18' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4-0613' | 'gpt-4-0314' | 'gpt-4-turbo-2024-04-09' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-1106' | 'watt-tool-8b' | 'watt-tool-70b' - `scoring_mode` 'binary' | 'numeric_uniform' - `max_score` integer — Maximum value of the numeric score scale (minimum is always 0). Only used when scoring_mode is 'numeric_uniform'. - `score_instructions` string, nullable — Optional free-text instructions describing how to assign values on the numeric scale. Only used when scoring_mode is 'numeric_uniform'. - `widget` WidgetConfigOutput - `variant` 'tiny' | 'compact' | 'full' | 'expandable' - `placement` 'top-left' | 'top' | 'top-right' | 'bottom-left' | 'bottom' | 'bottom-right' - `expandable` 'never' | 'mobile' | 'desktop' | 'always' - `avatar` union — The avatar of the widget - OrbAvatar - `type` 'orb' — The type of the avatar - `color_1` string — The first color of the avatar - `color_2` string — The second color of the avatar - URLAvatar - `type` 'url' — The type of the avatar - `custom_url` string — The custom URL of the avatar - ImageAvatar - `type` 'image' — The type of the avatar - `url` string — The URL of the avatar - `feedback_mode` 'none' | 'during' | 'end' - `end_feedback` WidgetEndFeedbackConfig - `type` 'rating' - `bg_color` string — The background color of the widget - `text_color` string — The text color of the widget - `btn_color` string — The button color of the widget - `btn_text_color` string — The button text color of the widget - `border_color` string — The border color of the widget - `focus_color` string — The focus color of the widget - `border_radius` integer, nullable — The border radius of the widget - `btn_radius` integer, nullable — The button radius of the widget - `action_text` string, nullable — The action text of the widget - `start_call_text` string, nullable — The start call text of the widget - `end_call_text` string, nullable — The end call text of the widget - `expand_text` string, nullable — The expand text of the widget - `listening_text` string, nullable — The text to display when the agent is listening - `speaking_text` string, nullable — The text to display when the agent is speaking - `shareable_page_text` string, nullable — The text to display when sharing - `shareable_page_show_terms` boolean — Whether to show terms and conditions on the shareable page - `terms_text` string, nullable — The text to display for terms and conditions - `terms_html` string, nullable — The HTML to display for terms and conditions - `terms_key` string, nullable — The key to display for terms and conditions - `show_avatar_when_collapsed` boolean, nullable — Whether to show the avatar when the widget is collapsed - `disable_banner` boolean — Whether to disable the banner - `override_link` string, nullable — The override link for the widget - `markdown_link_allowed_hosts` AllowlistItem[] — List of allowed hostnames for clickable markdown links. Use { hostname: '*' } to allow any domain. Empty means no links are allowed. - `hostname` string, required — The hostname of the allowed origin - `markdown_link_include_www` boolean — Whether to automatically include www. variants of allowed hosts - `markdown_link_allow_http` boolean — Whether to allow http:// in addition to https:// for allowed hosts - `mic_muting_enabled` boolean — Whether to enable mic muting - `transcript_enabled` boolean — Whether the widget should show the conversation transcript as it goes on - `text_input_enabled` boolean — Whether the user should be able to send text messages - `conversation_mode_toggle_enabled` boolean — Whether to enable the conversation mode toggle in the widget - `default_expanded` boolean — Whether the widget should be expanded by default - `always_expanded` boolean — Whether the widget should always be expanded - `dismissible` boolean — Whether the widget can be dismissed by the user - `show_agent_status` boolean — Whether to show agent working/done/error status during tool use - `show_conversation_id` boolean — Whether to show the conversation ID after disconnection. - `strip_audio_tags` boolean — Whether to strip audio markup from messages. - `syntax_highlight_theme` 'light' | 'dark', nullable — Theme for code block syntax highlighting. Defaults to auto-detection by the widget when not set. - `text_contents` WidgetTextContents - `main_label` string, nullable — Call to action displayed inside the compact and full variants. - `start_call` string, nullable — Text and ARIA label for the start call button. - `start_chat` string, nullable — Text and ARIA label for the start chat button (text only) - `new_call` string, nullable — Text and ARIA label for the new call button. Displayed when the caller already finished at least one call in order ot start the next one. - `end_call` string, nullable — Text and ARIA label for the end call button. - `mute_microphone` string, nullable — ARIA label for the mute microphone button. - `change_language` string, nullable — ARIA label for the change language dropdown. - `collapse` string, nullable — ARIA label for the collapse button. - `expand` string, nullable — ARIA label for the expand button. - `copied` string, nullable — Text displayed when the user copies a value using the copy button. - `accept_terms` string, nullable — Text and ARIA label for the accept terms button. - `dismiss_terms` string, nullable — Text and ARIA label for the cancel terms button. - `listening_status` string, nullable — Status displayed when the agent is listening. - `speaking_status` string, nullable — Status displayed when the agent is speaking. - `connecting_status` string, nullable — Status displayed when the agent is connecting. - `chatting_status` string, nullable — Status displayed when the agent is chatting (text only) - `input_label` string, nullable — ARIA label for the text message input. - `input_placeholder` string, nullable — Placeholder text for the text message input. - `input_placeholder_text_only` string, nullable — Placeholder text for the text message input (text only) - `input_placeholder_new_conversation` string, nullable — Placeholder text for the text message input when starting a new conversation (text only) - `user_ended_conversation` string, nullable — Information message displayed when the user ends the conversation. - `agent_ended_conversation` string, nullable — Information message displayed when the agent ends the conversation. - `conversation_id` string, nullable — Text label used next to the conversation ID. - `error_occurred` string, nullable — Text label used when an error occurs. - `copy_id` string, nullable — Text and ARIA label used for the copy ID button. - `initiate_feedback` string, nullable — Text displayed to prompt the user for feedback. - `request_follow_up_feedback` string, nullable — Text displayed to request additional feedback details. - `thanks_for_feedback` string, nullable — Text displayed to thank the user for providing feedback. - `thanks_for_feedback_details` string, nullable — Additional text displayed explaining the value of user feedback. - `follow_up_feedback_placeholder` string, nullable — Placeholder text for the follow-up feedback input field. - `submit` string, nullable — Text and ARIA label for the submit button. - `go_back` string, nullable — Text and ARIA label for the go back button. - `send_message` string, nullable — Text and ARIA label for the send message button. - `text_mode` string, nullable — Text and ARIA label for the switch to text mode button. - `voice_mode` string, nullable — Text and ARIA label for the switch to voice mode button. - `switched_to_text_mode` string, nullable — Toast notification displayed when switching to text mode. - `switched_to_voice_mode` string, nullable — Toast notification displayed when switching to voice mode. - `copy` string, nullable — Text and ARIA label for the copy button. - `download` string, nullable — Text and ARIA label for the download button. - `wrap` string, nullable — Text and ARIA label for the wrap toggle button. - `agent_working` string, nullable — Status text displayed when the agent is processing a tool call. - `agent_done` string, nullable — Status text displayed when the agent finishes processing a tool call. - `agent_error` string, nullable — Status text displayed when the agent encounters an error during a tool call. - `attach_file` string, nullable — Text and ARIA label for the attach file button. - `remove_file` string, nullable — ARIA label for the remove file button. - `file_upload_error` string, nullable — Error message displayed when a file fails to upload. - `file_type_unsupported` string, nullable — Error message displayed when an unsupported file type is selected. Followed by the list of accepted types. - `file_too_large` string, nullable — Error message displayed when a file exceeds the maximum size limit. - `file_limit_reached` string, nullable — Error message displayed when the maximum number of files for a conversation is reached. - `typing_indicator` string, nullable — Status text displayed while the agent is typing. - `styles` WidgetStyles - `base` string, nullable — The base background color. - `base_hover` string, nullable — The color of the base background when hovered. - `base_active` string, nullable — The color of the base background when active (clicked). - `base_border` string, nullable — The color of the border against the base background. - `base_subtle` string, nullable — The color of subtle text against the base background. - `base_primary` string, nullable — The color of primary text against the base background. - `base_error` string, nullable — The color of error text against the base background. - `accent` string, nullable — The accent background color. - `accent_hover` string, nullable — The color of the accent background when hovered. - `accent_active` string, nullable — The color of the accent background when active (clicked). - `accent_border` string, nullable — The color of the border against the accent background. - `accent_subtle` string, nullable — The color of subtle text against the accent background. - `accent_primary` string, nullable — The color of primary text against the accent background. - `overlay_padding` number, nullable — The padding around the edges of the viewport. - `button_radius` number, nullable — The radius of the buttons. - `input_radius` number, nullable — The radius of the input fields. - `bubble_radius` number, nullable — The radius of the chat bubbles. - `sheet_radius` number, nullable — The default radius of sheets. - `compact_sheet_radius` number, nullable — The radius of the sheet in compact mode. - `dropdown_sheet_radius` number, nullable — The radius of the dropdown sheet. - `show_resize_button` boolean — Whether to show the resize button - `language_selector` boolean — Whether to show the language selector - `supports_text_only` boolean — Whether the widget can switch to text only mode - `custom_avatar_path` string, nullable — The custom avatar path - `language_presets` object — Language presets for the widget - `data_collection` object — Data collection settings - `data_collection_scopes` object — Scope per data collection item ID. Missing keys default to conversation scope. - `analysis_items` AgentAnalysisItemsOutput - `evaluation_criteria` union[] - union - AttachedUserEvaluationRef - `source` 'user', required - `analysis_item_id` string, required — Id of the referenced user evaluation item. - `version_id` string, nullable — Primary item version whose result feeds scoring. None tracks the item's latest published version. - `additional_version_ids` string[] — Extra item versions to also run for comparison (A/B). These are executed and stored but excluded from scoring; the primary version_id is the one that scores. - `scope` 'conversation' | 'agent' - `weight` number, nullable — Optional relative weight for aggregate scoring. - AttachedSystemEvaluationRef - `source` 'system', required - `analysis_item_id` '__system_eval_criteria_sentiment' | '__system_eval_criteria_frustration', required — Id of the referenced built-in system evaluation. - `scope` 'conversation' | 'agent' - `weight` number, nullable — Optional relative weight for aggregate scoring. - `data_collection` union[] - union - AttachedUserDataCollectionRef - `source` 'user', required - `analysis_item_id` string, required — Id of the referenced user data-collection item. - `version_id` string, nullable — Pinned item version. None tracks the item's latest published version. - `scope` 'conversation' | 'agent' - AttachedSystemDataCollectionRef - `source` 'system', required - `analysis_item_id` '__system_data_collection_topic', required — Id of the referenced built-in system data-collection item. - `scope` 'conversation' | 'agent' - `overrides` ConversationInitiationClientDataConfigOutput - `conversation_config_override` ConversationConfigClientOverrideConfigOutput - `asr` ASRConversationalConfigOverrideConfig - `keywords` boolean — Whether to allow overriding the keywords field. - `turn` TurnConfigOverrideConfig - `soft_timeout_config` SoftTimeoutConfigOverrideConfig - `message` boolean — Whether to allow overriding the message field. - `tts` TTSConversationalConfigOverrideConfig - `model_id` boolean — Whether to allow overriding the model_id field. - `voice_id` boolean — Whether to allow overriding the voice_id field. - `stability` boolean — Whether to allow overriding the stability field. - `speed` boolean — Whether to allow overriding the speed field. - `similarity_boost` boolean — Whether to allow overriding the similarity_boost field. - `conversation` ConversationConfigOverrideConfig - `text_only` boolean — Whether to allow overriding the text_only field. - `agent` AgentConfigOverrideConfig - `first_message` boolean — Whether to allow overriding the first_message field. - `language` boolean — Whether to allow overriding the language field. - `max_conversation_duration_message` boolean — Whether to allow overriding the max_conversation_duration_message field. - `prompt` PromptAgentAPIModelOverrideConfig - `prompt` boolean — Whether to allow overriding the prompt field. - `llm` boolean — Whether to allow overriding the llm field. - `tool_ids` boolean — Whether to allow overriding the tool_ids field. - `native_mcp_server_ids` boolean — Whether to allow overriding the native_mcp_server_ids field. - `knowledge_base` boolean — Whether to allow overriding the knowledge_base field. - `custom_llm_extra_body` boolean — Whether to include custom LLM extra body - `enable_conversation_initiation_client_data_from_webhook` boolean — Whether to enable conversation initiation client data from webhooks - `enable_starting_workflow_node_id_from_client` boolean — Whether clients may pass starting_workflow_node_id in initiation client data; if false, sending it fails conversation start. - `workspace_overrides` AgentWorkspaceOverridesOutput - `conversation_initiation_client_data_webhook` ConversationInitiationClientDataWebhook - `url` string, required — The URL to send the webhook to - `request_headers` object, required — The headers to send with the webhook request - `webhooks` ConvAIWebhooks - `post_call_webhook_id` string, nullable - `events` WebhookEventType[] — List of event types to send via webhook. Options: transcript, audio, call_initiation_failure, unredacted_transcript, unredacted_audio. - `transcript_format` 'json' | 'opentelemetry' - `send_audio` boolean, nullable — DEPRECATED: Use 'events' field instead. Whether to send audio data with post-call webhooks for ConvAI conversations - `testing` AgentTestingSettings — Settings for agent testing configuration. - `attached_tests` AttachedTestModel[] — List of test IDs that should be run for this agent - `test_id` string, required - `workflow_node_id` string, nullable - `archived` boolean — Whether the agent is archived - `guardrails` GuardrailsV1Output - `version` '1' - `focus` FocusGuardrail - `is_enabled` boolean - `prompt_injection` PromptInjectionGuardrail - `is_enabled` boolean - `content` ContentGuardrailOutput - `execution_mode` 'streaming' | 'blocking' - `config` ContentConfig - `sexual` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `violence` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `harassment` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `self_harm` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `profanity` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `religion_or_politics` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `medical_and_legal_information` ContentThresholdGuardrail - `is_enabled` boolean - `threshold` union - … - `trigger_action` union - EndCallTriggerAction - `type` 'end_call' - RetryTriggerAction - `type` 'retry' - `feedback` string — Custom feedback to inject into the agent when retrying after guardrail trigger. - `moderation` object, nullable - `execution_mode` 'streaming' | 'blocking' - `config` ModerationConfig - `sexual` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `violence` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `violence_graphic` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `harassment` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `harassment_threatening` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `hate` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `hate_threatening` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `self_harm_instructions` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `self_harm` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `self_harm_intent` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `sexual_minors` ThresholdGuardrail - `is_enabled` boolean - `threshold` number - `custom` CustomGuardrailOutput — Container for custom guardrails, matching ModerationGuardrail pattern - `config` CustomGuardrailsConfigOutput — Config container for custom guardrails list - `configs` CustomGuardrailConfig[] - `is_enabled` boolean - `name` string, required — User-facing name for this guardrail - `prompt` string, required — Instruction describing what to block, e.g. 'don't talk about politics' - `execution_mode` 'streaming' | 'blocking' - `model` 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'claude-haiku-4-5' | 'claude-sonnet-4-6' | 'gpt-5.4-nano' | 'gpt-5.4-mini' — LLM model to use for custom guardrail evaluation - `history_message_count` integer — How much recent history the guardrail sees before the reply it evaluates, counted in user messages (the agent replies between them are included too). The guardrail always gets a single transcript ending in the evaluated reply, marked 'AGENT [current reply]:'. 0 (default) adds no prior history (just that line); 1 adds the latest user message onward. - `history_include_tool_calls` boolean — When enabled, the history also renders the agent's tool calls, their input arguments, and the tool results, interleaved with the text, so an action between two agent messages is visible. Off by default: history shows only user and agent text. Tool payloads can be large and can mislead smaller evaluator models, so enabling this raises token cost. - `trigger_action` union - … - `evaluate_full_response_only` boolean — Evaluate once against the complete non-TTS response instead of cumulative partials. Requires blocking mode. - `summary_language` string, nullable — Language for all conversation analysis outputs (summaries, titles, evaluation rationales, data collection rationales). If not set, the language will be inferred from the conversation. Must be one of the supported conversation languages. - `auto_translate_transcript_to_app_language` boolean, nullable — When enabled, a conversation transcript is automatically translated to the viewer's application language when they open the transcript page. If not set or false, transcripts are shown in their original language unless the viewer manually selects a translation. - `auth` AuthSettings - `enable_auth` boolean — If set to true, starting a conversation with an agent will require a signed token - `allowlist` AllowlistItem[] — A list of hosts that are allowed to start conversations with the agent - `hostname` string, required — The hostname of the allowed origin - `require_origin_header` boolean — When enabled, connections with no origin header will be rejected. If the allowlist is empty, this option has no effect. - `shareable_token` string, nullable — A shareable token that can be used to start a conversation with the agent - `call_limits` AgentCallLimits - `agent_concurrency_limit` integer — The maximum number of concurrent conversations. -1 indicates that there is no maximum - `daily_limit` integer — The maximum number of conversations per day - `bursting_enabled` boolean — Whether to enable bursting. If true, exceeding workspace concurrency limit will be allowed up to 3 times the limit. Calls will be charged at double rate when exceeding the limit. - `privacy` PrivacyConfigOutput - `record_voice` boolean — Whether to record the conversation - `retention_days` integer — The number of days to retain the conversation. -1 indicates there is no retention limit - `delete_transcript_and_pii` boolean — Whether to delete the transcript and PII - `delete_audio` boolean — Whether to delete the audio - `apply_to_existing_conversations` boolean — Whether to apply the privacy settings to existing conversations - `zero_retention_mode` boolean — Whether to enable zero retention mode - no PII data is stored - `conversation_history_redaction` ConversationHistoryRedactionConfig - `enabled` boolean — Whether conversation history redaction is enabled - `entities` ConfigEntityType[] — The entities to redact from the conversation transcript, audio and analysis. Use top-level types like 'name', 'email_address', or dot notation for specific subtypes like 'name.full_name'. - `trust_context` 'unknown' | 'low' | 'high' — The trust context in which the agent operates. UNKNOWN: not yet classified (existing agents created before this feature). LOW: serves untrusted external participants (e.g. customer support, sales) — outputs should be vetted and tool access scoped. HIGH: serves the owner (e.g. personal assistant) — full tool access is appropriate. - `analysis_llm` 'gpt-4o-mini' | 'gpt-4o' | 'gpt-4' | 'gpt-4-turbo' | 'gpt-4.1' | 'gpt-4.1-mini' | 'gpt-4.1-nano' | 'gpt-5' | 'gpt-5.1' | 'gpt-5.2' | 'gpt-5.2-chat-latest' | 'gpt-5.4' | 'gpt-5.4-mini' | 'gpt-5.4-nano' | 'gpt-5.5' | 'gpt-5.6-sol' | 'gpt-5.6-terra' | 'gpt-5.6-luna' | 'gpt-5-mini' | 'gpt-5-nano' | 'gpt-3.5-turbo' | 'gemini-1.5-pro' | 'gemini-1.5-flash' | 'gemini-2.0-flash' | 'gemini-2.0-flash-lite' | 'gemini-2.5-flash-lite' | 'gemini-2.5-flash' | 'gemini-3-pro-preview' | 'gemini-3-flash-preview' | 'gemini-3.1-pro-preview' | 'gemini-3.1-flash-lite-preview' | 'gemini-3.1-flash-lite' | 'gemini-3.5-flash' | 'gemini-3.5-flash-lite' | 'claude-sonnet-4-5' | 'claude-opus-4-7' | 'claude-opus-4-8' | 'claude-sonnet-4-6' | 'claude-sonnet-5' | 'claude-sonnet-4' | 'claude-haiku-4-5' | 'claude-3-7-sonnet' | 'claude-3-5-sonnet' | 'claude-3-5-sonnet-v1' | 'claude-3-haiku' | 'grok-beta' | 'custom-llm' | 'qwen3-4b' | 'qwen3-30b-a3b' | 'qwen36-35b-a3b' | 'qwen35-397b-a17b' | 'gpt-oss-20b' | 'gpt-oss-120b' | 'glm-45-air-fp8' | 'gemini-2.5-flash-preview-09-2025' | 'gemini-2.5-flash-lite-preview-09-2025' | 'gemini-2.5-flash-preview-05-20' | 'gemini-2.5-flash-preview-04-17' | 'gemini-2.5-flash-lite-preview-06-17' | 'gemini-2.0-flash-lite-001' | 'gemini-2.0-flash-001' | 'gemini-1.5-flash-002' | 'gemini-1.5-flash-001' | 'gemini-1.5-pro-002' | 'gemini-1.5-pro-001' | 'claude-sonnet-4@20250514' | 'claude-sonnet-4-5@20250929' | 'claude-haiku-4-5@20251001' | 'claude-3-7-sonnet@20250219' | 'claude-3-5-sonnet@20240620' | 'claude-3-5-sonnet-v2@20241022' | 'claude-3-haiku@20240307' | 'gpt-5-2025-08-07' | 'gpt-5.1-2025-11-13' | 'gpt-5.2-2025-12-11' | 'gpt-5.4-2026-03-05' | 'gpt-5.4-mini-2026-03-17' | 'gpt-5.4-nano-2026-03-17' | 'gpt-5.5-2026-04-23' | 'gpt-5-mini-2025-08-07' | 'gpt-5-nano-2025-08-07' | 'gpt-4.1-2025-04-14' | 'gpt-4.1-mini-2025-04-14' | 'gpt-4.1-nano-2025-04-14' | 'gpt-4o-mini-2024-07-18' | 'gpt-4o-2024-11-20' | 'gpt-4o-2024-08-06' | 'gpt-4o-2024-05-13' | 'gpt-4-0613' | 'gpt-4-0314' | 'gpt-4-turbo-2024-04-09' | 'gpt-3.5-turbo-0125' | 'gpt-3.5-turbo-1106' | 'watt-tool-8b' | 'watt-tool-70b' - `topic_discovery` TopicDiscoverySettings — Per-agent topic-discovery configuration. Cadence and analysis window are managed internally; this only exposes the customer-facing on/off toggle. - `sentiment_analysis` SentimentAnalysisSettings - `alerting` AlertingSettingsResponse — Customer-facing view of alerting settings. Unlike AdminAlertingSettingsResponse, it has no internal_notifiers field: those are ElevenLabs-internal delivery channels whose URLs must never be returned outside the admin API. - `monitor_configs` object - `auto_resolve_after_inactive_minutes` integer, nullable - `notifiers` AlertingWebhookNotifierResponse[] - `type` 'webhook' - `webhook_id` string, required - `safety` SafetyResponseModel - `is_blocked_ivc` boolean - `is_blocked_non_ivc` boolean - `ignore_safety_evaluation` boolean - `phone_numbers` union[] — The phone numbers of the agent - union - GetPhoneNumberTwilioResponseModel - `phone_number` string, required — Phone number - `label` string, required — Label for the phone number - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls - `phone_number_id` string, required — The ID of the phone number - `assigned_agent` PhoneNumberAgentInfo - `agent_id` string, required — The ID of the agent - `agent_name` string, required — The name of the agent - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number. - `branch_id` string, nullable — Agent branch to use for calls to this number. - `provider` 'twilio' — Phone provider - GetPhoneNumberExotelResponseModel - `phone_number` string, required — Phone number - `label` string, required — Label for the phone number - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls - `phone_number_id` string, required — The ID of the phone number - `assigned_agent` PhoneNumberAgentInfo - `agent_id` string, required — The ID of the agent - `agent_name` string, required — The name of the agent - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number. - `branch_id` string, nullable — Agent branch to use for calls to this number. - `provider` 'exotel' — Phone provider - GetPhoneNumberSIPTrunkResponseModel - `phone_number` string, required — Phone number - `label` string, required — Label for the phone number - `supports_inbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports inbound calls - `supports_outbound` boolean — This field is deprecated and will be removed in the future. Whether this phone number supports outbound calls - `phone_number_id` string, required — The ID of the phone number - `assigned_agent` PhoneNumberAgentInfo - `agent_id` string, required — The ID of the agent - `agent_name` string, required — The name of the agent - `environment` string, nullable — Environment to use for resolving environment variables on calls to this number. - `branch_id` string, nullable — Agent branch to use for calls to this number. - `provider` 'sip_trunk' — Phone provider - `provider_config` GetPhoneNumberOutboundSIPTrunkConfigResponseModel — SIP Trunk configuration details for a phone number - `address` string, required — Hostname or IP the SIP INVITE is sent to - `transport` 'auto' | 'udp' | 'tcp' | 'tls', required - `media_encryption` 'disabled' | 'allowed' | 'required', required - `headers` object — SIP headers for INVITE request - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers - `has_auth_credentials` boolean, required — Whether authentication credentials are configured - `username` string, nullable — SIP trunk username (if available) - `has_outbound_trunk` boolean — Whether a LiveKit SIP outbound trunk is configured - `enabled_codecs` MediaCodec[] — Media codecs that are offered in the SDP for outbound calls. If empty, all supported codecs are offered. - `outbound_trunk` GetPhoneNumberOutboundSIPTrunkConfigResponseModel — SIP Trunk configuration details for a phone number - `address` string, required — Hostname or IP the SIP INVITE is sent to - `transport` 'auto' | 'udp' | 'tcp' | 'tls', required - `media_encryption` 'disabled' | 'allowed' | 'required', required - `headers` object — SIP headers for INVITE request - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers - `has_auth_credentials` boolean, required — Whether authentication credentials are configured - `username` string, nullable — SIP trunk username (if available) - `has_outbound_trunk` boolean — Whether a LiveKit SIP outbound trunk is configured - `enabled_codecs` MediaCodec[] — Media codecs that are offered in the SDP for outbound calls. If empty, all supported codecs are offered. - `inbound_trunk` GetPhoneNumberInboundSIPTrunkConfigResponseModel - `allowed_addresses` string[], required — List of IP addresses that are allowed to use the trunk. Each item in the list can be an individual IP address or a Classless Inter-Domain Routing notation representing a CIDR block. - `allowed_numbers` string[], nullable, required — List of phone numbers that are allowed to use the trunk. - `media_encryption` 'disabled' | 'allowed' | 'required', required - `has_auth_credentials` boolean, required — Whether authentication credentials are configured - `username` string, nullable — SIP trunk username (if available) - `remote_domains` string[], nullable — Domains of remote SIP servers used to validate TLS certificates. - `attributes_to_headers` object — Map of dynamic variable name to header name for attributes_to_headers - `livekit_stack` 'standard' | 'static', required - `store_sip_messages` boolean — Whether to store SIP messages for this phone number. - `whatsapp_accounts` GetWhatsAppAccountResponse[] — WhatsApp accounts assigned to the agent - `business_account_id` string, required - `phone_number_id` string, required - `business_account_name` string, required - `phone_number_name` string, required - `phone_number` string, required - `assigned_agent_id` string, nullable - `enable_messaging` boolean - `enable_audio_message_response` boolean - `enable_typing_indicator` boolean - `assigned_agent_name` string, nullable, required - `is_token_expired` boolean - `workflow` AgentWorkflowResponseModel - `edges` object, required - `nodes` object, required - `prevent_subagent_loops` boolean, required — Whether to prevent loops in the workflow execution. - `access_info` ResourceAccessInfo - `is_creator` boolean, required — Whether the user making the request is the creator of the agent - `creator_name` string, required — Name of the agent's creator - `creator_email` string, required — Email of the agent's creator - `role` 'admin' | 'editor' | 'commenter' | 'viewer', required — The role of the user making the request - `anonymous_access_level_override` 'admin' | 'editor' | 'commenter' | 'viewer', nullable — The access level for anonymous users. If None, the resource is not shared publicly. - `access_source` 'creator' | 'explicit' | 'workspace_admin' | 'workspace_default', nullable — Why the requesting user has access to this resource. 'creator' = caller is the owner. 'explicit' = caller (or one of their workspace groups) is listed in role_to_group_ids beyond the workspace-wide everyone group. 'workspace_default' = the workspace-wide everyone group is listed in role_to_group_ids (every non-anon workspace member, including admins, sees this resource). 'workspace_admin' = caller is a workspace admin and the admin seat is the *only* path to access; reserved for docs nobody else can see. Lets the UI disclose why an admin-bypass viewer sees a doc that wasn't explicitly shared with them. - `tags` string[] — Agent tags used to categorize the agent - `version_id` string, nullable — The ID of the version the agent is on - `branch_id` string, nullable — The ID of the branch the agent is on - `main_branch_id` string, nullable — The ID of the main branch for this agent ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation.md) · [All operations](https://skmtc.net/elevenlabs/apis/elevenlabs-api-documentation/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/elevenlabs/elevenlabs-api-documentation/versions/57d56f34628a/schema)