> ## Documentation Index > Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Update Agent > Update an existing agent on the v1 API. Changes state - verify before retry Update an existing agent. Send only the fields you want to change. The request is scoped to the authenticated organization automatically. ## When to use this * **Prompt iteration**: change `prompt_text` or `system_prompt_text` on a draft version while tuning agent behavior. * **Rewiring**: point the agent at a different voice, LLM, transcriber, phone number, or knowledge base without recreating it. * **Publishing**: set `is_published` to promote a draft version once it is ready for production traffic. * **Fallback configuration**: enable LLM or STT fallbacks so calls survive a provider outage (see the sections below). A `400 Bad Request` means a field failed validation; `404 Not Found` means the agent does not exist in this workspace. See [Errors](/docs/api-reference/errors) for the standard error format. ## Minimal publish request ```json theme={null} { "version_number": 1, "is_published": true } ``` Send only the fields you intend to change. The remaining schema groups cover advanced prompt, speech, fallback, analysis, function, and routing settings. ## Post-Call Analysis LLM Use `post_call_analysis_llm_id` on this endpoint to set or clear the LLM used for post-call field extraction on a draft version. | Request field | Result | | ------------------------------------------------- | ------------------------------------------------------------ | | `post_call_analysis_llm_id: "llm_A1B2C3D4E5F6G7"` | Uses that LLM for post-call extraction. | | `post_call_analysis_llm_id: null` | Clears the override and falls back to the workspace default. | | Omit `post_call_analysis_llm_id` | Leaves the existing setting unchanged. | Send `version_number` with the request. Published versions cannot be edited, except when publishing a draft. ## Publishing And Phone Number Assignment Phone number assignment becomes live only when you publish a draft. If you send `inbound_phone_number_id` or `outbound_phone_number_id`, include `is_published: true` in the same request so DialNexa can claim the number for that published version. Sending a phone number ID without `is_published: true` is ignored for live routing. Use an empty string to detach an inbound or outbound phone number while publishing. For outbound numbers, DialNexa can return `409 Conflict` if changing or removing the number would break active workflows that still use that number in Voice Call nodes. Pause those workflows first, then retry. ## Fallback STT Use `fallback_stt_enabled`, `stt_fallback_transcriber_id`, and `stt_fallback_wait_ms` to configure fallback transcription. Pick the fallback transcriber ID from [List Fallback Transcribers](/docs/api-reference/v1/transcribers/fallback), then pass the selected ID here. The fallback transcriber ID must differ from the effective primary `transcriber_id`. ## Speech And Model Settings Use `boosted_keywords` when a cascaded Deepgram or Soniox agent needs recognition hints for names, products, localities, or other uncommon terms. Send a comma-separated string. Terms can contain letters, numbers, and spaces only, with up to `100` normalized terms, `50` characters per term, and `2,000` total characters. Use `predictive_preprocessing_enabled` to pre-generate likely next replies between turns. Use `prompt_caching_enabled` only when DialNexa has enabled Prompt Caching for your workspace. If the feature is not enabled, the API returns `403 Forbidden`. ## Validation Rules The update request validates the effective draft configuration before saving. | Field | Rule | | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `prompt_text`, `welcome_message`, and `voicemail_message` | Must be valid Handlebars template text when they use `{{variable}}` syntax. | | `system_prompt_text` | Static system instructions. Use `prompt_text` for dynamic variables. | | `voice_model_id` | Must belong to the same provider as the effective `voice_id`. Omit it when changing voices so DialNexa can apply the recommended model. | | `stt_fallback_transcriber_id` | Required when fallback STT is enabled and must differ from the effective primary `transcriber_id`. Sending the same ID for both returns `400 Bad Request`. | | `default_dynamic_variables.agent_transfer_destinations` | Supports up to `7` pipe-separated transfer numbers. Each must be US `+1` or India `+91` with exactly `10` digits after the country code. | | `end_call_on_silence_sec` | Must be `15` to `30` seconds and more than `5` seconds above `reminder_message_interval` when reminders are configured. | | `max_call_duration_sec` | Must be `60` to `5,400` seconds for cascaded agents. Speech to Speech agents are capped at `3,600` seconds. | | Publishing | Can return `409 Conflict` if this agent is tied to a draft, waiting, scheduled, active, or running batch campaign. Resolve the campaign before publishing. | ## Verify the result Fetch the agent and confirm the intended version is published. If the update timed out, read the agent before repeating the request, especially when publishing or assigning a phone number. ## OpenAPI ````yaml PATCH /v1/agents/{id} openapi: 3.0.0 info: title: DialNexa API description: Public `/v1` REST API for the DialNexa voice AI platform. version: 1.0.0 servers: - url: https://api.dialnexa.com description: DialNexa production API security: - bearer: [] tags: - name: Agents - name: Batch Calls - name: Calls - name: Knowledge Base - name: Languages - name: LLMs - name: Phone Numbers - name: Transcribers - name: Webhooks - name: Voices - name: Workflows - name: Workflow Leads paths: /v1/agents/{id}: patch: tags: - Agents summary: Update Agent description: >- Updates the specified draft version of an agent. `version_number` is required. **Managing functions via this endpoint:** - Pass `agent_functions: [...]` to fully replace all functions for that version. - Pass `agent_functions: []` to remove all functions. - Omit `agent_functions` entirely to leave existing functions untouched. **Post-call analysis LLM:** - Pass `post_call_analysis_llm_id`, for example `llm_A1B2C3D4E5F6G7`, to set the LLM used for post-call field extraction. - Pass `null` to clear the override and revert to the organization default. - Omit the field to leave it unchanged. **Phone number assignment:** - `inbound_phone_number_id` and `outbound_phone_number_id` are applied to live routing only when `is_published: true` is included in the same request. - Sending a phone number ID without `is_published: true` leaves live routing unchanged. - Pass an empty string to detach a phone number while publishing. - Outbound changes can return `409 Conflict` when active workflows still use the number. Pause those workflows before retrying. Published versions cannot be updated, except to set `is_published: true` to publish a draft. operationId: updateAgent parameters: - name: id required: true in: path description: Agent ID schema: example: agent_2g7Xy3tY53gRlp type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateAgentRequest' examples: request: summary: Update a draft agent version value: version_number: 1 title: Customer Support Agent llm_id: llm_A1B2C3D4E5F6G7 fallback_stt_enabled: true stt_fallback_transcriber_id: trs_soniox post_call_analysis_llm_id: llm_A1B2C3D4E5F6G7 clearPostCallAnalysisLlm: summary: Clear post-call analysis LLM override value: version_number: 1 post_call_analysis_llm_id: null publishWithOutboundNumber: summary: Publish a draft with an outbound number value: version_number: 1 is_published: true outbound_phone_number_id: phn_def456 detachOutboundNumber: summary: Publish while detaching an outbound number value: version_number: 2 is_published: true outbound_phone_number_id: '' responses: '200': description: Agent updated successfully. content: application/json: schema: $ref: '#/components/schemas/Agents' examples: success: summary: Successful response value: id: agent_2g7Xy3tY53gRlp folder_id: null current_version_number: 1 timezone: Asia/Kolkata agent_type: Single_Prompt_Agent pipeline_type: Cascaded webhook_id: null current_version: agent_id: agent_2g7Xy3tY53gRlp version_number: 1 version_title: Version 1 title: Customer Support Agent is_published: false language_id: lang_en_in voice_id: voice_abc123 llm_id: llm_A1B2C3D4E5F6G7 transcriber_id: trs_deepgram_nova_2 fallback_stt_enabled: true stt_fallback_transcriber_id: trs_soniox post_call_analysis_llm_id: llm_A1B2C3D4E5F6G7 versions: - agent_id: agent_2g7Xy3tY53gRlp version_number: 1 version_title: Version 1 title: Customer Support Agent is_published: false language_id: lang_en_in voice_id: voice_abc123 llm_id: llm_A1B2C3D4E5F6G7 transcriber_id: trs_deepgram_nova_2 fallback_stt_enabled: true stt_fallback_transcriber_id: trs_soniox post_call_analysis_llm_id: llm_A1B2C3D4E5F6G7 '400': description: Invalid body or attempting to update a published version. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: summary: 400 Bad Request value: statusCode: 400 message: Request validation failed error: Bad Request '401': description: Unauthorized. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: summary: 401 Unauthorized value: statusCode: 401 message: API key is missing or invalid error: Unauthorized '403': description: Forbidden. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: summary: 403 Forbidden value: statusCode: 403 message: You do not have permission to access this resource error: Forbidden '404': description: Agent or version not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: summary: 404 Not Found value: statusCode: 404 message: Agent not found error: Not Found '409': description: Phone number assignment conflicts with active workflows. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: phoneNumberUsedInActiveWorkflows: summary: 409 Conflict value: statusCode: 409 message: >- Cannot bind outbound_phone_number_id "phn_def456" to this agent because it is currently used by active workflows. Pause those workflows first, then retry. error: Conflict '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: error: summary: 500 Internal Server Error value: statusCode: 500 message: Internal server error error: Internal Server Error security: - bearer: [] components: schemas: UpdateAgentRequest: type: object properties: background_sound: type: string description: Background sound file or identifier background_sound_volume: type: number minimum: 0 maximum: 2 description: Volume of background sound (0 to 2) ambient_noise: type: boolean description: Enable or disable ambient noise playback on the call responsiveness: type: number minimum: 0 maximum: 5 description: Responsiveness level from 0 to 1. interruption_sensitivity: type: number minimum: 0 maximum: 1 description: Interruption sensitivity level (0 to 1) response_eagerness: type: number minimum: 0 maximum: 1 description: >- How eagerly the agent responds (0 to 1). Only applied when transcriber is Soniox. backchanneling: type: boolean description: Enable or disable backchanneling backchannel_frequency: type: number minimum: 0 maximum: 1 description: Frequency of backchannel responses example: 0.5 transcription_mode: type: string enum: - optimize_for_speed - optimize_for_accuracy description: Mode for transcription denoising_mode: type: string enum: - remove_noise - remove_noise_and_speech nullable: true description: Mode for denoising audio input speech_normalization: type: boolean description: Enable or disable speech normalization transcript_formatting: type: boolean description: Enable or disable transcript formatting backchannel_keywords: type: string description: Comma-separated list of backchannel keywords boosted_keywords: type: string description: >- Comma-separated recognition hints for supported Deepgram and Soniox transcribers. Terms can contain letters, numbers, and spaces only. The normalized list supports up to 100 terms, 50 characters per term, and 2000 total characters. maxLength: 2000 example: DialNexa, Nexa Prime, customer success reminder_message_interval: type: number description: Interval between reminder messages (in seconds) reminder_message_frequency: type: number description: Frequency of reminder messages transcriber_id: type: string nullable: true description: ID of the transcriber catalog entry fallback_stt_enabled: type: boolean description: Enable parallel fallback STT for this agent stt_fallback_transcriber_id: type: string nullable: true description: >- Fallback STT transcriber catalog entry. Required when fallback_stt_enabled is true and must differ from the effective primary transcriber_id. stt_fallback_wait_ms: type: number minimum: 0 description: Milliseconds to wait for primary STT after fallback finalizes first audio_cache_enabled: type: boolean description: Enable TTS audio caching for this agent version_number: type: number description: Version number of the agent to update example: 1 folder_id: type: string description: ID of the folder this agent belongs to example: fld_abc123xyz789 pipeline_type: type: string description: >- Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS pipeline. Speech_To_Speech = direct speech model. enum: - Cascaded - Speech_To_Speech example: Cascaded title: type: string description: Title of the agent (max 70 characters) example: Customer Support Agent maxLength: 70 version_title: type: string description: >- Version title (optional, will be auto-generated if not provided, max 35 characters) example: Version 1.1 nullable: true maxLength: 35 description: type: string description: Description of the agent example: This agent handles customer support inquiries timezone: type: string description: Timezone for the agent example: Asia/Kolkata inbound_phone_number_id: type: string description: >- ID of the inbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live inbound routing only when `is_published: true` is sent in the same request. Pass an empty string to detach while publishing. system_prompt_text: type: string description: >- Static system instructions for the agent. Use prompt_text for dynamic content via {{variable}} syntax. example: You are a helpful customer support agent named Sarah. outbound_phone_number_id: type: string description: >- ID of the outbound phone number to use for this agent. Must be an existing phone number ID in your organization. Applied to live outbound routing only when `is_published: true` is sent in the same request. Pass an empty string to detach while publishing. Active workflows using the number can cause a 409 conflict. language_id: type: string description: ID of the language the agent speaks example: lng_59a9ce4a91334686933a llm_id: type: string description: ID of the LLM associated with the agent example: A1B2C3D4E5F6G7 llm_temperature: type: number description: >- temperature value for the LLM which controls how creative the model responses are example: 0.1 default: 0.1 voice_id: type: string description: ID of the voice used by the agent example: VOICE123456789 webhook_id: type: string description: ID of the webhook associated with the agent example: wh_12345678901234 prompt_text: type: string description: >- Main instructions for the agent. Supports Handlebars template syntax such as {{variable}} for dynamic content. Must be valid Handlebars template text. example: Hello, how can I assist you today? node_positions: type: string description: >- Node positions for Conversational_Flow_Agent type (stored as JSON string) example: '{"id" : 1, "positions" : {"x": 100, "y": 200}}' conversation_start_type: type: string description: Who starts the conversation example: user enum: - user - agent_dynamic - agent_defined welcome_message: type: string description: >- Opening message spoken by the agent at the start of the call. Supports Handlebars template syntax such as {{variable}} and must be valid Handlebars template text. example: Welcome to our service! allow_interruptions: type: boolean description: Whether the agent allows interruptions example: true structured_output: type: boolean description: Whether the reponse should adhere to a structure or not example: true json_output_instructions: type: object description: Instructions for JSON output example: format: detailed knowledge_base_ids: description: IDs of the knowledge bases attached to this agent version example: - kb_abc123 - kb_def456 type: array items: type: string kb_max_chunks: type: number description: Maximum number of RAG chunks to fetch (1-10) example: 5 minimum: 1 maximum: 10 kb_min_score: type: number description: Minimum similarity score threshold for RAG results (0-1) example: 0.5 minimum: 0 maximum: 1 is_published: type: boolean description: >- Publish this draft version. When true, phone number IDs in the same request are claimed for live routing. example: false update_deployment: type: boolean description: Whether to allow updating a published version example: false default_dynamic_variables: type: object description: >- Default values for dynamic variables used in Handlebars templates. For call-transfer flows, agent_transfer_destinations accepts up to 7 pipe-separated phone numbers. Each number must use US +1 or India +91 and exactly 10 digits after the country code. example: firstName: John lastName: Doe courseType: Math fallback_llm_enabled: type: boolean description: Enable fallback LLM for this agent example: false llm_fallback_delay_ms: type: number description: Milliseconds to wait before triggering the fallback LLM example: 500 nullable: true llm_fallback_model: type: string description: ID (llms.id) of the LLM to use as fallback example: abc123xyz789ab nullable: true predictive_preprocessing_enabled: type: boolean description: Enable predictive preprocessing for this agent version example: false voice_model_id: type: string description: >- Speech synthesis model for the selected voice. The model must belong to the same provider as voice_id. Omit this field when you want DialNexa to apply the recommended model. For ElevenLabs voices, use eleven_flash_v2_5 where supported. To find supported models for one voice, call GET /v1/voices/{voice_id}/voice-models. example: '254' agent_identity: type: string description: >- Agent identity (required for Conversational_Flow_Agent type on update) example: You are a helpful customer support agent named Sarah. agent_background: type: string description: >- Agent background (required for Conversational_Flow_Agent type on update) example: >- You have 5 years of experience in customer support and specialize in helping customers with technical issues. post_call_analysis: description: Post call analysis configuration example: - field_name: customer_satisfaction field_type: NUMBER field_description: Customer satisfaction rating type: array items: type: object required: - field_name - field_type - field_description properties: field_name: type: string field_type: type: string enum: - NUMBER - STRING - BOOLEAN - ENUM field_description: type: string postcall_analysis: description: Post call analysis configuration (alternative field name) example: - field_name: customer_satisfaction field_type: NUMBER field_description: Customer satisfaction rating type: array items: type: object required: - field_name - field_type - field_description properties: field_name: type: string field_type: type: string enum: - NUMBER - STRING - BOOLEAN - ENUM field_description: type: string agent_functions: type: array description: >- Agent functions - full replace for this version. Pass empty array to clear all. items: type: object properties: displayName: type: string example: Book Calendar type: type: string enum: - end_call - call_transfer - custom - check_calendar_availability - book_calendar - integration description: type: string example: Book appointments config: type: object example: api_key: xxx post_call_analysis_llm_id: type: string nullable: true description: >- LLM ID used for post-call analysis extraction. Pass a signed LLM ID such as llm_A1B2C3D4E5F6G7 to set an override, null to clear it, or omit the field to leave the existing setting unchanged. example: llm_A1B2C3D4E5F6G7 prompt_caching_enabled: type: boolean description: >- Enable OpenAI Prompt Caching for this agent version. DialNexa must enable this feature for your workspace. example: false required: - version_number Agents: type: object properties: id: type: string example: agent_2g7Xy3tY53gRlp description: Signed agent ID folder_id: type: string nullable: true current_version_number: type: integer nullable: true timezone: type: string nullable: true agent_type: type: string enum: - Single_Prompt_Agent - Conversational_Flow_Agent pipeline_type: type: string enum: - Cascaded - Speech_To_Speech nullable: true webhook_id: type: string nullable: true current_version: type: object properties: agent_id: type: string version_number: type: integer version_title: type: string nullable: true title: type: string nullable: true is_published: type: boolean language_id: type: string nullable: true voice_id: type: string nullable: true llm_id: type: string nullable: true transcriber_id: type: string nullable: true fallback_stt_enabled: type: boolean stt_fallback_transcriber_id: type: string nullable: true post_call_analysis_llm_id: type: string nullable: true nullable: true versions: type: array items: type: object properties: agent_id: type: string version_number: type: integer version_title: type: string nullable: true title: type: string nullable: true is_published: type: boolean language_id: type: string nullable: true voice_id: type: string nullable: true llm_id: type: string nullable: true transcriber_id: type: string nullable: true fallback_stt_enabled: type: boolean stt_fallback_transcriber_id: type: string nullable: true post_call_analysis_llm_id: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - agent_type ErrorResponse: type: object properties: statusCode: type: integer example: 400 message: oneOf: - type: string - type: array items: type: string example: phone_number must be a valid E.164 phone number error: type: string example: Bad Request required: - statusCode - message - error securitySchemes: bearer: scheme: bearer type: http ````