> ## 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
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
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 legacy `/agents2` update uses a separate body (`UpdateAgents2BodyDto`). Review the request schema for `/v1/agents/{id}` in the panel on this page before migrating.
## 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 REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/agents/{id}:
patch:
tags:
- Agents V1
- V1
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: AgentsV1Controller_update
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/UpdateAgentDto'
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:
UpdateAgentDto:
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 list of boosted keywords
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
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: System prompt text for the agent
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: Prompt text used by the agent
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: Welcome message for the agent
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 templates
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: Voice model ID to use for the agent
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
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
bearerFormat: JWT
type: http
````