> ## Documentation Index > Fetch the complete documentation index at: https://docs.itellico.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update an agent > Update an existing agent with partial data. Only fields provided in the request will be updated. ## OpenAPI ````yaml https://api.itellico.ai/v1/openapi.json patch /v1/accounts/{account_id}/agents/{agent_id} openapi: 3.1.0 info: title: itellicoAI API v1 version: 1.0.0 description: >- Public REST API for managing accounts, agents, telephony resources, and conversations. Authentication is via API key in the `X-API-Key` header. termsOfService: https://itellico.ai/legal/terms-and-conditions/ contact: name: itellicoAI Support email: support@itellico.ai license: name: Proprietary servers: - url: https://api.itellico.ai description: Production security: - APIKeyAuth: [] tags: - name: Accounts description: >- Identify the current account context and fetch core account metadata to bootstrap API usage. - name: Subaccounts description: >- Create and manage child accounts under a parent to model tenant hierarchies and delegated access. - name: Agents description: >- Define and configure conversational agents (model, transcriber, voice, behavior) used in calls and automations. - name: Providers description: >- Discover available AI model, transcriber, and voice catalogs for the current account when configuring agents. - name: Phone Numbers description: >- Manage BYOC phone numbers bound to your account; route inbound calls to agents and enable outbound calling. - name: SIP Trunks description: >- Manage BYOC SIP trunk connectivity (origination/termination endpoints and allowed IPs) used by phone numbers. - name: Calls description: >- Create, list, inspect, and connect voice calls across phone and web channels. - name: Conversations description: List and inspect conversation activity across web and telephony channels. - name: Analytics description: Usage analytics and reporting endpoints for conversation activity. paths: /v1/accounts/{account_id}/agents/{agent_id}: patch: tags: - Agents summary: Update an agent description: >- Update an existing agent with partial data. Only fields provided in the request will be updated. operationId: updateAgent parameters: - in: path name: account_id schema: title: Account Id type: string required: true - in: path name: agent_id schema: format: uuid4 title: Agent Id type: string required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentUpdateSchemaPatch' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/AgentResponseSchema' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '422': description: Unprocessable Content content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrorSchema' security: - APIKeyAuth: [] components: schemas: AgentUpdateSchemaPatch: properties: name: anyOf: - maxLength: 50 type: string - type: 'null' description: The name of the agent. Only used for your own reference. title: Name initial_message: anyOf: - $ref: '#/components/schemas/InitialMessageSchema' - type: 'null' description: >- Configuration for the agent's initial message when starting a conversation. ambient_sound: anyOf: - $ref: '#/components/schemas/AmbientSoundSchema' - type: 'null' description: Configuration for ambient background sounds during the conversation. max_duration_seconds: anyOf: - maximum: 7200 minimum: 10 type: integer - type: 'null' description: >- Maximum allowed length for the conversation in seconds. Maximum is 7200 seconds (2 hours). title: Max Duration Seconds inactivity_settings: anyOf: - $ref: '#/components/schemas/InactivitySettings' - type: 'null' description: >- Configuration for handling user inactivity and silence during conversations. note: anyOf: - maxLength: 5000 type: string - type: 'null' description: Internal notes about the agent. title: Note tags: anyOf: - items: type: string type: array - type: 'null' description: List of tags to categorize the agent. title: Tags interrupt_settings: anyOf: - $ref: '#/components/schemas/InterruptSettings' - type: 'null' description: Configuration for how the agent handles user interruptions. response_timing: anyOf: - $ref: '#/components/schemas/ResponseTimingSchema' - type: 'null' description: >- Configuration for agent response timing and conversation flow control. metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: >- Custom metadata for the agent. Store any additional key-value pairs that your application needs. title: Metadata capture_settings: anyOf: - $ref: '#/components/schemas/CaptureSettingsSchema' - type: 'null' description: Capture settings configuration for recording and artifact settings. volume: anyOf: - $ref: '#/components/schemas/VolumeSchema' - type: 'null' description: >- Volume settings for different call types and voice adjustment control. denoising: anyOf: - $ref: '#/components/schemas/DenoisingSchema' - type: 'null' description: Denoising/noise cancellation settings for enhanced audio quality. allow_auto_hangup: anyOf: - type: boolean - type: 'null' description: >- Whether the AI may automatically end the call when the conversation has concluded. title: Allow Auto Hangup allow_caller_recording_opt_out: anyOf: - type: boolean - type: 'null' description: >- Whether callers may request that recording stop and captured audio be deleted. title: Allow Caller Recording Opt Out model: anyOf: - additionalProperties: true type: object - type: 'null' description: Language model configuration for the agent. Partial updates allowed. title: Model transcriber: anyOf: - discriminator: mapping: azure: $ref: '#/components/schemas/AzureTranscriberSchema' cartesia: $ref: '#/components/schemas/CartesiaTranscriberSchema' deepgram: $ref: '#/components/schemas/DeepgramTranscriberSchema' elevenlabs: $ref: '#/components/schemas/ElevenLabsTranscriberSchema' soniox: $ref: '#/components/schemas/SonioxTranscriberSchema' propertyName: provider oneOf: - $ref: '#/components/schemas/AzureTranscriberSchema' - $ref: '#/components/schemas/DeepgramTranscriberSchema' - $ref: '#/components/schemas/CartesiaTranscriberSchema' - $ref: '#/components/schemas/ElevenLabsTranscriberSchema' - $ref: '#/components/schemas/SonioxTranscriberSchema' - type: 'null' description: >- Transcriber (speech-to-text) configuration for the agent. Partial updates allowed. title: Transcriber voice: anyOf: - additionalProperties: true type: object - type: 'null' description: Text-to-speech configuration for the agent. Partial updates allowed. title: Voice title: AgentUpdateSchemaPatch type: object AgentResponseSchema: description: Response returned after agent operations (create, get, update) properties: id: description: >- Unique identifier for the agent. Use this ID to reference the agent in API calls for updates, deletion, or starting conversations. format: uuid4 title: Id type: string account_id: description: Unique identifier for the account that owns this agent. format: uuid4 title: Account Id type: string name: description: >- The display name of the agent as configured. This is for your reference and internal organization. title: Name type: string initial_message: $ref: '#/components/schemas/InitialMessageSchema' description: >- Configuration for the agent's initial message when starting a conversation. ambient_sound: $ref: '#/components/schemas/AmbientSoundSchema' description: Configuration for ambient background sounds during the conversation. max_duration_seconds: anyOf: - type: integer - type: 'null' description: >- The maximum conversation duration configured for this agent in seconds. Maximum allowed is 7200 seconds (2 hours). title: Max Duration Seconds inactivity_settings: $ref: '#/components/schemas/InactivitySettings' description: >- Configuration for handling user inactivity and silence during conversations. note: anyOf: - type: string - type: 'null' description: Internal notes about the agent for your team's reference. title: Note tags: anyOf: - items: type: string type: array - type: 'null' description: >- List of tags assigned to this agent for categorization and filtering. title: Tags interrupt_settings: anyOf: - $ref: '#/components/schemas/InterruptSettings' - type: 'null' description: >- Configuration for how the agent handles user interruptions during conversation. response_timing: $ref: '#/components/schemas/ResponseTimingSchema' description: >- Configuration for agent response timing and conversation flow control. model: anyOf: - additionalProperties: true type: object - type: 'null' description: Language model configuration for the agent. title: Model transcriber: anyOf: - additionalProperties: true type: object - type: 'null' description: Speech-to-text configuration for the agent. title: Transcriber voice: anyOf: - additionalProperties: true type: object - type: 'null' description: Text-to-speech configuration for the agent. title: Voice metadata: anyOf: - additionalProperties: true type: object - type: 'null' description: Custom metadata associated with the agent. title: Metadata capture_settings: anyOf: - $ref: '#/components/schemas/CaptureSettingsSchema' - type: 'null' description: Capture settings configuration for recording and artifact settings. volume: anyOf: - $ref: '#/components/schemas/VolumeSchema' - type: 'null' description: >- Volume settings for different call types and voice adjustment control. denoising: anyOf: - $ref: '#/components/schemas/DenoisingSchema' - type: 'null' description: >- Denoising/noise cancellation settings for enhanced audio quality powered by Krisp. allow_auto_hangup: description: >- Whether the AI may automatically end the call when the conversation has concluded. title: Allow Auto Hangup type: boolean allow_caller_recording_opt_out: description: >- Whether callers may request that recording stop and captured audio be deleted. title: Allow Caller Recording Opt Out type: boolean created: anyOf: - format: date-time type: string - type: 'null' description: Date-time of when the agent was created (ISO 8601 on output). title: Created modified: anyOf: - format: date-time type: string - type: 'null' description: Date-time of when the agent was last updated (ISO 8601 on output). title: Modified required: - id - account_id - name - initial_message - ambient_sound - inactivity_settings - response_timing - allow_auto_hangup - allow_caller_recording_opt_out title: AgentResponseSchema type: object ErrorSchema: description: |- Standard error response payload for all API endpoints. Follows industry best practices (similar to Stripe, RetellAI): - code: Machine-readable error identifier for programmatic handling - message: Human-readable description for display - detail: Optional additional context for debugging - errors: Optional list of field-level validation errors examples: - code: not_found detail: Agent with UUID 123e4567-e89b-12d3-a456-426614174000 does not exist message: Resource not found - code: validation_error errors: - field: body.email message: Invalid email format type: value_error - field: body.name message: Field required type: missing message: Validation failed properties: code: description: Machine-readable error code (e.g., 'not_found', 'validation_error') title: Code type: string message: description: Human-readable error message title: Message type: string detail: anyOf: - type: string - type: 'null' description: Optional detailed context for debugging title: Detail errors: anyOf: - items: $ref: '#/components/schemas/FieldErrorSchema' type: array - type: 'null' description: Field-level validation errors (for 422 responses) title: Errors required: - code - message title: ErrorSchema type: object InitialMessageSchema: description: >- Configuration for the agent's initial message when starting a conversation properties: message: anyOf: - maxLength: 500 type: string - type: 'null' default: '' description: >- The first message that the agent will say when starting a conversation. If not set, the agent will wait for the user to speak first. Use this to set a friendly greeting like 'Hello! How can I help you today?'. You can add variables in double curly brackets, for example: {{customer_name}} or {{company_name}}. title: Message mode: allOf: - $ref: '#/components/schemas/InitialMessageMode' default: fixed_message description: >- This is the mode for the first message. Default is 'fixed_message'. Use: - 'fixed_message' to have the assistant speak first with the configured message above. - 'user_first' to have the assistant wait for the user to speak first. - 'dynamic_message' to have the assistant speak first with a message generated by the model based on the conversation state (using model.messages at call start, or call context at transfer points). delay_ms: default: 0 description: >- Delay in milliseconds before the agent speaks the initial message, giving users time to prepare. Valid range is [0, 5000]. Default is 0 (speak immediately). Only applies when mode is 'fixed_message' or 'dynamic_message'. maximum: 5000 minimum: 0 title: Delay Ms type: integer interruptible: default: false description: >- Whether the user can interrupt the agent while it's speaking the initial message. When false, the agent will complete its initial greeting before listening. Default is false for a smoother start to conversations. title: Interruptible type: boolean title: InitialMessageSchema type: object AmbientSoundSchema: description: Configuration for ambient background sounds during the conversation properties: source: anyOf: - $ref: '#/components/schemas/AmbientSound' - type: 'null' description: >- The source of ambient environment sound to add to the call to make the experience more realistic. For example, 'customer_service_center' adds call center background noise, 'open_plan_office' adds office chatter. Set to null to have no background sound. volume: default: 0.5 description: >- Controls the volume of the ambient sound. Value ranging from [0.0, 1.0]. 0.0 is muted, 1.0 is maximum volume, and 0.5 is normal/default volume. maximum: 1 minimum: 0 title: Volume type: number title: AmbientSoundSchema type: object InactivitySettings: description: Configuration for handling user inactivity during conversations properties: reminder_timeout_ms: anyOf: - maximum: 300000 minimum: 5000 type: integer - type: 'null' default: 10000 description: >- Time in milliseconds to wait before sending a reminder when user is silent. Only used when reminder_max_count > 0. Minimum 5000ms (5 seconds), maximum 300000ms (5 minutes). title: Reminder Timeout Ms reminder_max_count: default: 2 description: >- Maximum number of reminder messages to send when reminders are enabled. Only used when reminder_timeout_ms is set. maximum: 10 minimum: 0 title: Reminder Max Count type: integer end_call_timeout_ms: anyOf: - maximum: 600000 minimum: 10000 type: integer - type: 'null' description: >- Time in milliseconds of user inactivity before ending the call. Only used when reminders are disabled (reminder_timeout_ms is null). Set to null to never auto-end calls. Minimum 10000ms (10 seconds), maximum 600000ms (10 minutes). title: End Call Timeout Ms reset_on_activity: default: true description: >- Whether to reset the reminder count when the user becomes active again. When true (default), the counter resets after user activity. When false, reminders are cumulative throughout the conversation. title: Reset On Activity type: boolean title: InactivitySettings type: object InterruptSettings: description: >- Configuration for how the agent handles user interruptions during conversation properties: enabled: default: true description: >- Whether users can interrupt the agent while it's speaking. When true, the agent will stop speaking and listen when the user starts talking. title: Enabled type: boolean min_words: default: 0 description: >- Minimum number of words the user must speak to trigger an interruption. Helps prevent accidental interruptions from brief sounds. maximum: 10 minimum: 0 title: Min Words type: integer min_speech_seconds: default: 0.2 description: >- Minimum duration in seconds of continuous speech required to trigger an interruption. Helps filter out brief noises. maximum: 2 minimum: 0 title: Min Speech Seconds type: number title: InterruptSettings type: object ResponseTimingSchema: description: Configuration for agent response timing and conversation flow control properties: min_endpointing_delay_seconds: default: 0.1 description: >- Delay in seconds to wait after user stops speaking before the agent starts responding. Prevents the agent from responding too quickly during natural pauses in speech. Default is 0.1 seconds. maximum: 5 minimum: 0 title: Min Endpointing Delay Seconds type: number title: ResponseTimingSchema type: object CaptureSettingsSchema: description: Agent capture settings configuration. properties: recording_enabled: anyOf: - type: boolean - type: 'null' default: true description: >- Whether to record the agent's calls. Set to false to disable recording. title: Recording Enabled title: CaptureSettingsSchema type: object VolumeSchema: description: Agent volume settings for audio output control. properties: web: default: 0.5 description: >- Volume level for web-based calls. Range [0.0, 1.0] where 0.0 is muted, 0.5 is normal volume, and 1.0 is maximum volume. maximum: 1 minimum: 0 title: Web type: number telephony: default: 0.5 description: >- Volume level for telephony/SIP calls. Range [0.0, 1.0] where 0.0 is muted, 0.5 is normal volume, and 1.0 is maximum volume. maximum: 1 minimum: 0 title: Telephony type: number allow_adjustment: default: true description: >- Whether to allow users to adjust volume through voice commands (e.g., 'speak louder', 'speak quieter'). When enabled, adds volume control as an available tool for the agent. title: Allow Adjustment type: boolean title: VolumeSchema type: object DenoisingSchema: description: Agent denoising/noise cancellation settings for enhanced audio quality. properties: web: default: true description: >- Enable enhanced noise cancellation for web-based calls powered by Krisp technology. title: Web type: boolean telephony: default: true description: >- Enable enhanced noise cancellation for telephony/SIP calls with optimized phone audio processing powered by Krisp. title: Telephony type: boolean title: DenoisingSchema type: object AzureTranscriberSchema: description: Azure-specific transcriber configuration. properties: provider: const: azure default: azure title: Provider type: string language: anyOf: - enum: - af-ZA - am-ET - ar-AE - ar-BH - ar-DZ - ar-EG - ar-IL - ar-IQ - ar-JO - ar-KW - ar-LB - ar-LY - ar-MA - ar-OM - ar-PS - ar-QA - ar-SA - ar-SY - ar-TN - ar-YE - az-AZ - bg-BG - bn-IN - bs-BA - ca-ES - cs-CZ - cy-GB - da-DK - de-AT - de-CH - de-DE - el-GR - en-AU - en-CA - en-GB - en-GH - en-HK - en-IE - en-IN - en-KE - en-NG - en-NZ - en-PH - en-SG - en-TZ - en-US - en-ZA - es-AR - es-BO - es-CL - es-CO - es-CR - es-CU - es-DO - es-EC - es-ES - es-GQ - es-GT - es-HN - es-MX - es-NI - es-PA - es-PE - es-PR - es-PY - es-SV - es-US - es-UY - es-VE - et-EE - eu-ES - fa-IR - fi-FI - fil-PH - fr-BE - fr-CA - fr-CH - fr-FR - ga-IE - gl-ES - gu-IN - he-IL - hi-IN - hr-HR - hu-HU - hy-AM - id-ID - is-IS - it-CH - it-IT - ja-JP - jv-ID - ka-GE - kk-KZ - km-KH - kn-IN - ko-KR - lo-LA - lt-LT - lv-LV - mk-MK - ml-IN - mn-MN - mr-IN - ms-MY - mt-MT - my-MM - nb-NO - ne-NP - nl-BE - nl-NL - pa-IN - pl-PL - ps-AF - pt-BR - pt-PT - ro-RO - ru-RU - si-LK - sk-SK - sl-SI - so-SO - sq-AL - sr-RS - sv-SE - sw-KE - sw-TZ - ta-IN - te-IN - th-TH - tr-TR - uk-UA - ur-IN - uz-UZ - vi-VN - wuu-CN - yue-CN - zh-CN - zh-CN-shandong - zh-CN-sichuan - zh-HK - zh-TW - zu-ZA type: string - type: 'null' description: >- Language for transcription (see Azure Speech Service docs for supported languages) title: Language title: AzureTranscriberSchema type: object CartesiaTranscriberSchema: description: Cartesia-specific transcriber configuration. properties: provider: const: cartesia default: cartesia title: Provider type: string model: anyOf: - const: ink-whisper type: string - type: 'null' description: Cartesia Ink Whisper streaming STT model title: Model language: anyOf: - enum: - en - zh - de - es - ru - ko - fr - ja - pt - tr - pl - ca - nl - ar - sv - it - id - hi - fi - vi - he - uk - el - ms - cs - ro - da - hu - ta - 'no' - th - ur - hr - bg - lt - la - mi - ml - cy - sk - te - fa - lv - bn - sr - az - sl - kn - et - mk - br - eu - is - hy - ne - mn - bs - kk - sq - sw - gl - mr - pa - si - km - sn - yo - so - af - oc - ka - be - tg - sd - gu - am - yi - lo - uz - fo - ht - ps - tk - nn - mt - sa - lb - my - bo - tl - mg - as - tt - haw - ln - ha - ba - jw - su - yue type: string - type: 'null' description: >- Language for transcription (ISO-639-1 code; defaults to Cartesia's provider default) title: Language title: CartesiaTranscriberSchema type: object DeepgramTranscriberSchema: description: Deepgram-specific transcriber configuration. properties: provider: const: deepgram default: deepgram title: Provider type: string model: anyOf: - enum: - flux-general-en - flux-general-multi - nova-3:general - nova-3:medical - nova-2:general - nova-2:phonecall - nova-2:meeting - nova-2:conversationalai type: string - type: 'null' description: Deepgram model to use (matches our YAML configuration) title: Model language: anyOf: - enum: - bg - ca - cs - da - da-DK - de - de-CH - el - en - en-AU - en-GB - en-IN - en-NZ - en-US - es - es-419 - es-LATAM - et - fi - fr - fr-CA - hi - hi-Latn - hu - id - it - ja - ko - ko-KR - lt - lv - ms - multi - nl - nl-BE - 'no' - pl - pt - pt-BR - ro - ru - sk - sv - sv-SE - ta - taq - th - th-TH - tr - uk - vi - zh - zh-CN - zh-Hans - zh-Hant - zh-TW type: string - type: 'null' description: >- Language for transcription (see Deepgram docs for supported languages) title: Language keywords: anyOf: - items: type: string type: array - type: 'null' description: Keywords to help model pick up use-case specific words title: Keywords languages: anyOf: - items: type: string type: array - type: 'null' description: >- Optional Deepgram Flux multilingual language hints. Used with model='flux-general-multi'; omit or send an empty list to let Flux auto-detect across all supported languages. title: Languages title: DeepgramTranscriberSchema type: object ElevenLabsTranscriberSchema: description: ElevenLabs Scribe realtime transcriber configuration. properties: provider: const: elevenlabs default: elevenlabs title: Provider type: string model: anyOf: - const: scribe_v2_realtime type: string - type: 'null' description: ElevenLabs Scribe v2 Realtime streaming STT model title: Model language: anyOf: - type: string - type: 'null' description: >- Language for transcription. Scribe accepts ISO-639-1 or ISO-639-3 codes; use the catalog for supported values. title: Language title: ElevenLabsTranscriberSchema type: object SonioxTranscriberSchema: description: Soniox realtime transcriber configuration. properties: provider: const: soniox default: soniox title: Provider type: string model: anyOf: - const: stt-rt-v4 type: string - type: 'null' description: Soniox v4 realtime streaming STT model title: Model language: anyOf: - type: string - type: 'null' description: Optional primary language hint. Soniox can auto-detect without this. title: Language languages: anyOf: - items: type: string type: array - type: 'null' description: Optional list of language hints for Soniox automatic detection. title: Languages keywords: anyOf: - items: type: string type: array - type: 'null' description: >- Recognition terms to bias transcription. Mapped to Soniox context.terms by the worker runtime. title: Keywords language_hints: anyOf: - items: type: string type: array - type: 'null' description: Soniox language hints, using ISO language codes such as 'de'. title: Language Hints language_hints_strict: anyOf: - type: boolean - type: 'null' description: Restrict recognition to the configured language hints. title: Language Hints Strict context: anyOf: - additionalProperties: true type: object - type: string - type: 'null' description: Soniox context object/string for domain terms and expected text. title: Context enable_speaker_diarization: anyOf: - type: boolean - type: 'null' description: Annotate tokens with speaker IDs. title: Enable Speaker Diarization enable_language_identification: anyOf: - type: boolean - type: 'null' description: Annotate tokens with detected language IDs. title: Enable Language Identification max_endpoint_delay_ms: anyOf: - maximum: 3000 minimum: 500 type: integer - type: 'null' description: Maximum endpoint detection delay in milliseconds. title: Max Endpoint Delay Ms eu_hosted: anyOf: - type: boolean - type: 'null' description: Use the Soniox EU realtime endpoint when true. title: Eu Hosted title: SonioxTranscriberSchema type: object FieldErrorSchema: description: Schema for individual field validation errors. properties: field: description: Field path (e.g., 'body.name', 'query.page') title: Field type: string message: description: Human-readable error message title: Message type: string type: description: Error type (e.g., 'value_error', 'type_error') title: Type type: string required: - field - message - type title: FieldErrorSchema type: object InitialMessageMode: description: How the agent should handle the initial message enum: - fixed_message - user_first - dynamic_message title: InitialMessageMode type: string AmbientSound: description: Available ambient background sounds to enhance conversation realism enum: - open_plan_office - customer_service_center - internet_cafe - urban_street - rural_outdoors - ac_fan title: AmbientSound type: string securitySchemes: APIKeyAuth: type: apiKey in: header name: X-API-Key ````