> ## 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.
# Create Agent
> Create a new AI voice 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.
Agents are the core building block in DialNexa. Each agent defines how an AI-powered call should sound and behave - what it says, how it responds, and what it can do.
## When to use this
Use this endpoint to create agents programmatically as part of an onboarding flow, template system, or multi-tenant setup. The request is scoped to the authenticated organization automatically.
## Before you begin
Fetch a `language_id` from [List Languages](/docs/api-reference/v1/languages/list) and a `voice_id` from [List Voices](/docs/api-reference/v1/voices/list). Creating an agent does not publish its first version.
## Minimal request
Start with the four required fields. Add advanced speech, model, fallback, analysis, routing, and function settings only when the basic agent works:
```json theme={null}
{
"title": "Customer Support Agent",
"language_id": "lang_en_in",
"voice_id": "voice_abc123",
"prompt_text": "Greet the caller, understand the issue, and summarize the next step."
}
```
The request panel contains every advanced field. Treat omitted optional fields as the safest starting point rather than copying the entire schema.
## Fallback STT And Post-Call Analysis
Use `fallback_stt_enabled` and `stt_fallback_transcriber_id` to configure fallback transcription on the first draft version. Pick the fallback transcriber ID from [List Fallback Transcribers](/docs/api-reference/v1/transcribers/fallback).
If you need post-call fields at creation time, pass `post_call_analysis`. To change the LLM used for extracting those fields after creation, use [Update Agent](/docs/api-reference/v1/agents/update) with `post_call_analysis_llm_id`.
## Phone Numbers And Predictive Preprocessing
You can include `inbound_phone_number_id` and `outbound_phone_number_id` when creating the first draft version. The IDs must belong to the authenticated workspace. Creating the agent stores those IDs on the draft, but live dispatch routing is claimed only when the version is published through [Update Agent](/docs/api-reference/v1/agents/update) with `is_published: true`.
Use `predictive_preprocessing_enabled` to turn on predictive preprocessing for the first draft version when your agent should pre-generate likely next replies between turns. This setting is most useful for cascaded agents with repeated, predictable scripts.
The legacy `/agents2` endpoint uses a separate, documentation-specific body (`CreateAgents2BodyDto`). If you are migrating from `/agents2`, do not assume the bodies are identical - review the request schema for `/v1/agents` in the panel on this page.
## Verify the result
Store the returned `id`, confirm `current_version.version_number` is `1`, then [publish the draft](/docs/api-reference/v1/agents/update) with `version_number: 1` and `is_published: true` before placing a call.
If the create request times out, list agents and search for the title before retrying. The contract does not currently publish an idempotency key.
## OpenAPI
````yaml POST /v1/agents
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:
post:
tags:
- Agents V1
- V1
summary: Create Agent
description: >-
Creates an agent with its first draft version. Optionally include
`agent_functions` and `post_call_analysis` in the body to set them at
creation time.
**Phone number fields:** `inbound_phone_number_id` and
`outbound_phone_number_id` must belong to the authenticated workspace.
On create, these IDs are stored on the draft version. Live dispatch
routing is claimed when the version is published through `PATCH
/v1/agents/{id}` with `is_published: true`.
operationId: AgentsV1Controller_create
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateAgentDto'
examples:
request:
summary: Create an agent
value:
title: Customer Support Agent
language_id: lang_en_in
voice_id: voice_abc123
llm_id: llm_A1B2C3D4E5F6G7
transcriber_id: trs_deepgram_nova_2
system_prompt_text: >-
You are a helpful support agent. Confirm the customer issue
and summarize next steps.
fallback_stt_enabled: true
stt_fallback_transcriber_id: trs_soniox
post_call_analysis:
- field_name: issue_type
field_type: STRING
field_description: Main customer issue discussed on the call
predictive_preprocessing_enabled: false
outbound_phone_number_id: phn_def456
agent_type: Single_Prompt_Agent
prompt_text: >-
You are a helpful support agent. Confirm the customer's
issue and summarize next steps.
responses:
'201':
description: Agent created 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 request body.
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 - missing or invalid API key.
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 - API key does not have access to this organization.
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
'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:
CreateAgentDto:
type: object
properties:
voicemail_detection:
type: boolean
description: Indicates whether voicemail detection is enabled
default: true
example: true
hangup_on_voicemail:
type: boolean
description: >-
Hang up immediately when voicemail is detected instead of leaving a
message
default: false
example: false
voicemail_message:
type: string
description: >-
Message played when voicemail is detected (only used when
hangup_on_voicemail is false)
example: Hi, please call us back at your convenience.
default: Please leave a message after the beep.
listen_for_keypad:
type: boolean
description: Whether the agent listens for keypad (DTMF) input from the caller
example: true
default: true
keypad_timeout_sec:
type: number
description: Seconds to wait for keypad input before timing out (0-15)
example: 5
default: 5
minimum: 0
maximum: 15
termination_key:
type: string
description: 'Single character key that ends the call (digits, * or #)'
example: '#'
default: '#'
digit_limit:
type: number
description: Maximum number of DTMF digits to collect from the caller (1-50)
example: 1
default: 1
minimum: 1
maximum: 50
end_call_on_silence_sec:
type: number
description: >-
Seconds of silence after which the call is automatically ended
(0-1800)
example: 180
default: 180
minimum: 0
maximum: 1800
max_call_duration_sec:
type: number
description: Maximum call duration in seconds before the call is forcibly ended
example: 600
default: 600
minimum: 0
pause_before_speaking_sec:
type: number
description: Seconds of silence inserted before the agent starts speaking
example: 0
default: 2
minimum: 0
ring_duration_sec:
type: number
description: >-
How long to let the phone ring before treating the call as
unanswered (seconds)
example: 30
default: 5
minimum: 1
background_sound:
type: string
description: Background sound file or identifier
background_sound_volume:
type: number
minimum: 0
maximum: 2
default: 1
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: 1
default: 0.5
description: Responsiveness level from 0 to 1.
interruption_sensitivity:
type: number
minimum: 0
maximum: 1
default: 0.5
description: Interruption sensitivity level (0 to 1)
response_eagerness:
type: number
minimum: 0
maximum: 1
default: 1
description: >-
How eagerly the agent responds (0 to 1). Only applied when
transcriber is Soniox.
backchanneling:
type: boolean
default: false
description: Enable or disable backchanneling
backchannel_frequency:
type: number
minimum: 0
maximum: 1
default: 0.5
description: Backchannel frequency from (0 to 1)
transcription_mode:
type: string
enum:
- optimize_for_speed
- optimize_for_accuracy
default: optimize_for_speed
description: Mode for transcription
denoising_mode:
type: string
enum:
- remove_noise
- remove_noise_and_speech
description: Mode for denoising audio input
speech_normalization:
type: boolean
default: false
description: Enable or disable speech normalization
transcript_formatting:
type: boolean
default: false
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
default: 9
description: Interval between reminder messages (in seconds)
reminder_message_frequency:
type: number
default: 1
description: Frequency of reminder messages
transcriber_id:
type: string
nullable: true
description: ID of the transcriber catalog entry
fallback_stt_enabled:
type: boolean
default: false
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
folder_id:
type: string
description: ID of the folder this agent belongs to
example: fld_abc123xyz789
agent_type:
type: string
description: Type of the agent
enum:
- Single_Prompt_Agent
- Conversational_Flow_Agent
example: Single_Prompt_Agent
default: Single_Prompt_Agent
pipeline_type:
type: string
description: >-
Pipeline subtype for Single_Prompt_Agent. Cascaded = ASR→LLM→TTS
pipeline. Speech_To_Speech = direct speech model. Null for
Conversational_Flow_Agent.
enum:
- Cascaded
- Speech_To_Speech
example: Cascaded
default: 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: null
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
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. Stored on the draft
at creation; live outbound routing is claimed when the version is
published.
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. Stored on the draft
at creation; live inbound routing is claimed when the version is
published.
llm_id:
type: string
description: ID of the LLM associated with the agent
example: A1B2C3D4E5F6G7
language_id:
type: string
description: ID of the language the agent speaks
example: '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?
system_prompt_text:
type: string
description: System prompt text for the agent
example: You are a helpful customer support agent named Sarah.
node_positions:
type: string
description: >-
Node positions for Conversational_Flow_Agent type (stored as JSON
string)
example: '{"node1": {"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
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
default_dynamic_variables:
type: object
description: Default values for dynamic variables used in templates
example:
firstName: John
lastName: Doe
courseType: Math
voice_model_id:
type: string
description: Voice model ID to use for the agent
example: voice_model_abc123
voice_speed:
type: number
description: Voice speed (0.25 to 4.0)
example: 1
minimum: 0.25
maximum: 4
voice_temperature:
type: number
description: Voice temperature (0.0 to 2.0)
example: 1
minimum: 0
maximum: 2
voice_volume:
type: number
description: Voice volume (0 to 10)
example: 1
minimum: 0
maximum: 10
voice_pitch:
type: number
description: Pitch adjustment of the voice (-1 to 1)
example: 0
minimum: -1
maximum: 1
llm_temperature:
type: number
description: LLM temperature (0.0 to 2.0)
example: 0.1
minimum: 0
maximum: 2
opt_out_sensitive_data_storage:
type: boolean
description: Opt out of sensitive data storage
example: false
opt_in_secure_urls:
type: boolean
description: Opt in to secure URLs
example: false
fallback_llm_enabled:
type: boolean
description: Enable fallback LLM for this agent
example: false
predictive_preprocessing_enabled:
type: boolean
description: Enable predictive preprocessing for this agent version
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
fallback_voices:
type: array
description: Fallback voices for TTS. Used when the primary voice is unavailable.
items:
type: object
properties:
voice_id:
type: string
example: VOICE123456789
voice_name:
type: string
example: Fallback Voice
provider_voice_id:
type: string
example: en-US-JennyNeural
provider:
type: string
example: azure
agent_functions:
type: array
description: >-
Functions the agent can invoke during a call (e.g. end call,
transfer, booking). Passed at create time; use PATCH to replace
later.
items:
type: object
required:
- displayName
- type
- description
properties:
displayName:
type: string
example: Book Calendar
type:
type: string
enum:
- end_call
- call_transfer
- custom
- check_calendar_availability
- book_calendar
- integration
example: book_calendar
description:
type: string
example: Books a calendar appointment for the caller
config:
type: object
example:
api_key: xxx
calendar_id: primary
post_call_analysis:
type: array
description: Fields to extract from the call transcript after the call ends.
items:
type: object
required:
- field_name
- field_type
- field_description
properties:
field_name:
type: string
example: customer_satisfaction
field_type:
type: string
enum:
- NUMBER
- STRING
- BOOLEAN
- ENUM
example: NUMBER
field_description:
type: string
example: Customer satisfaction rating from 1 to 5
postcall_analysis:
type: array
description: Alias for post_call_analysis (backward compatibility).
items:
type: object
properties:
field_name:
type: string
example: customer_satisfaction
field_type:
type: string
enum:
- NUMBER
- STRING
- BOOLEAN
- ENUM
example: NUMBER
field_description:
type: string
example: Customer satisfaction rating from 1 to 5
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.
required:
- title
- language_id
- voice_id
- prompt_text
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
````