DialNexa Agents API

openapi: 3.2.0
info:
  title: DialNexa Agents 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
paths:
  /v1/agents:
    post:
      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: createAgent
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            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: []
      summary: Create Agent
      tags:
      - Agents
    get:
      description: Returns all agents for your organization. Agent functions are NOT included in list responses - fetch a specific agent by ID to get its functions.
      operationId: listAgents
      parameters: []
      responses:
        '200':
          description: Agents returned successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  agents:
                    type: array
                    items:
                      $ref: '#/components/schemas/Agents'
              examples:
                success:
                  summary: Successful response
                  value:
                    agents:
                    - 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 query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid query parameters
                    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.
          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: []
      summary: List Agents
      tags:
      - Agents
  /v1/agents/{id}:
    patch:
      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
        '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
        '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
      security:
      - bearer: []
      summary: Update Agent
      tags:
      - Agents
    delete:
      description: Deletes an agent and all its versions. Historical call records remain available.
      operationId: deleteAgent
      parameters:
      - name: id
        required: true
        in: path
        description: Agent ID
        schema:
          example: agent_2g7Xy3tY53gRlp
          type: string
      responses:
        '200':
          description: Agent deleted successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    message: Agent deleted successfully
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Agent deleted successfully
        '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 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
        '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: []
      summary: Delete Agent
      tags:
      - Agents
    get:
      description: Returns the agent with all versions. Each version includes `agent_functions`, `pronunciations`, and `postcall_analysis` embedded.
      operationId: getAgent
      parameters:
      - name: id
        required: true
        in: path
        description: Agent ID
        schema:
          example: agent_2g7Xy3tY53gRlp
          type: string
      responses:
        '200':
          description: Agent returned with all versions and embedded agent_functions.
          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 agent ID format.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 400 Bad Request
                  value:
                    statusCode: 400
                    message: Invalid query parameters
                    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 - agent does not belong to your 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
        '404':
          description: Agent 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
        '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: []
      summary: Get Agent Details
      tags:
      - Agents
components:
  schemas:
    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
    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
          - 'null'
          enum:
          - remove_noise
          - remove_noise_and_speech
          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
        boost_dynamic_variables:
          type: boolean
          description: When true, sanitized values from test-call or batch-recipient dynamic variables are appended to boosted_keywords for that call. Configured terms keep priority. Applies to supported Deepgram and Soniox primary and fallback transcribers.
        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
          - 'null'
          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
          - 'null'
          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
          - 'null'
          description: Version title (optional, will be auto-generated if not provided, max 35 characters)
          example: Version 1.1
          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?


# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dialnexa/refs/heads/main/openapi/dialnexa-agents-api-openapi.yml