Create Agent

POST

agents2

Create a new agent (structured response)

curl --request POST \
  --url https://api.dialnexa.com/agents2 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "title": "Customer Support Agent",
  "llm": {
    "id": "llm_xxxxx",
    "settings": {
      "temperature": 0.1,
      "structured_output": true
    },
    "fallback": {
      "fallback_llm_enabled": false,
      "llm_fallback_model": "abc123xyz789ab",
      "fall_back_llm_id": "llm_abc123xyz789ab",
      "llm_fallback_delay_ms": 500
    }
  },
  "fallback_llm_enabled": false,
  "llm_fallback_model": "abc123xyz789ab",
  "llm_fallback_delay_ms": 500,
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "customer_satisfaction",
        "field_type": "NUMBER",
        "field_description": "Customer satisfaction rating"
      }
    ]
  }
}
'

import requests

url = "https://api.dialnexa.com/agents2"

payload = {
    "title": "Customer Support Agent",
    "llm": {
        "id": "llm_xxxxx",
        "settings": {
            "temperature": 0.1,
            "structured_output": True
        },
        "fallback": {
            "fallback_llm_enabled": False,
            "llm_fallback_model": "abc123xyz789ab",
            "fall_back_llm_id": "llm_abc123xyz789ab",
            "llm_fallback_delay_ms": 500
        }
    },
    "fallback_llm_enabled": False,
    "llm_fallback_model": "abc123xyz789ab",
    "llm_fallback_delay_ms": 500,
    "analysis": { "postcall_analysis": [
            {
                "field_name": "customer_satisfaction",
                "field_type": "NUMBER",
                "field_description": "Customer satisfaction rating"
            }
        ] }
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Customer Support Agent',
    llm: {
      id: 'llm_xxxxx',
      settings: {temperature: 0.1, structured_output: true},
      fallback: {
        fallback_llm_enabled: false,
        llm_fallback_model: 'abc123xyz789ab',
        fall_back_llm_id: 'llm_abc123xyz789ab',
        llm_fallback_delay_ms: 500
      }
    },
    fallback_llm_enabled: false,
    llm_fallback_model: 'abc123xyz789ab',
    llm_fallback_delay_ms: 500,
    analysis: {
      postcall_analysis: [
        {
          field_name: 'customer_satisfaction',
          field_type: 'NUMBER',
          field_description: 'Customer satisfaction rating'
        }
      ]
    }
  })
};

fetch('https://api.dialnexa.com/agents2', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/agents2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Customer Support Agent',
    'llm' => [
        'id' => 'llm_xxxxx',
        'settings' => [
                'temperature' => 0.1,
                'structured_output' => true
        ],
        'fallback' => [
                'fallback_llm_enabled' => false,
                'llm_fallback_model' => 'abc123xyz789ab',
                'fall_back_llm_id' => 'llm_abc123xyz789ab',
                'llm_fallback_delay_ms' => 500
        ]
    ],
    'fallback_llm_enabled' => false,
    'llm_fallback_model' => 'abc123xyz789ab',
    'llm_fallback_delay_ms' => 500,
    'analysis' => [
        'postcall_analysis' => [
                [
                                'field_name' => 'customer_satisfaction',
                                'field_type' => 'NUMBER',
                                'field_description' => 'Customer satisfaction rating'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/agents2"

	payload := strings.NewReader("{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/agents2")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/agents2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "number": 0,
  "is_published": false,
  "llm": {
    "id": "llm_xxxxx",
    "settings": {
      "temperature": 0.1,
      "structured_output": true
    },
    "fallback": {
      "fallback_llm_enabled": false,
      "llm_fallback_model": "abc123xyz789ab",
      "fall_back_llm_id": "llm_abc123xyz789ab",
      "llm_fallback_delay_ms": 500
    }
  },
  "fallback_llm_enabled": false,
  "llm_fallback_model": "llm_abc123xyz789ab",
  "fall_back_llm_id": "llm_abc123xyz789ab",
  "llm_fallback_delay_ms": 500,
  "transcriber_id": "tr0deepnova3xx",
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "customer_satisfaction",
        "field_type": "NUMBER",
        "field_description": "Customer satisfaction rating"
      }
    ]
  }
}

Legacy endpoint - deprecated. Unversioned endpoints are scheduled for removal on July 31, 2026. Use the /v1 version for new integrations. This endpoint remains available for existing integrations until then.

Agents are the core building block in DialNexa. Each agent defines how an AI-powered call should sound and behave, including what it says, how it responds, and what it can do.

When to use this

Use this endpoint to programmatically create agents as part of your onboarding flow, template system, or multi-tenant setup. For example, if each of your customers needs their own agent pre-configured with their business details, this lets you spin them up automatically.

Key fields

pipeline_type: Use Cascaded for the standard STT, LLM, and TTS pipeline. Use Speech_To_Speech for realtime speech models such as GPT realtime.
prompts.prompt_text: The system prompt that shapes the agent’s personality, instructions, and scope. Write it clearly; the LLM follows this closely.
voice: Pass a voice id from List Voices, or configure it inline.
speech.transcriber_id: Selects the primary STT provider for cascaded agents. Speech to Speech agents do not use a separate transcriber.
speech.fallback_stt_enabled: Enables a backup STT provider for cascaded agents. When enabled, also send speech.stt_fallback_transcriber_id.
speech.audio_cache_enabled: Caches repeated TTS phrases for lower latency on cascaded agents. Speech to Speech agents do not use TTS audio cache.
telephony.call_limits: Set how long a call can run, how long to wait before ending on silence, and how long to ring before giving up.
functions: Tools the agent can invoke mid-call, such as calendar booking, CRM lookups, or custom webhooks.
analysis.postcall_analysis: Fields to extract from the transcript after each call (e.g., CSAT score, intent, outcome).
metadata via dynamic variables: You can reference {{variable_name}} in your prompt; values are injected at call time from the call’s metadata object.

Pipeline Types

Pipeline type	Use it when	Notes
`Cascaded`	You want separate transcriber, LLM, and voice controls.	This is the default for single prompt agents and supports fallback STT, voice model pricing, and Audio Cache.
`Speech_To_Speech`	You want a realtime speech model to listen and speak directly.	The model selector is limited to speech-to-speech models, and voice model, transcriber, and Audio Cache controls are not used.

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

x-organization-id

string

required

RSA encrypted organization ID (base64 format)

Example:

"BASE64_ENCRYPTED_ORG_ID_HERE"

Body

application/json

Grouped request body. Fallback LLM: set llm.fallback.fallback_llm_enabled and llm.fallback.llm_fallback_model (or fall_back_llm_id). PCA: set analysis.postcall_analysis with field_name, field_type, field_description, and optional additional_fields.

title

string

Example:

"Customer Support Agent"

llm

object

Show child attributes

fallback_llm_enabled

boolean

Enable fallback LLM (flat alias; prefer llm.fallback.fallback_llm_enabled)

Example:

false

llm_fallback_model

string | null

Fallback LLM id (flat alias; prefer llm.fallback.llm_fallback_model)

Example:

"abc123xyz789ab"

llm_fallback_delay_ms

number | null

Fallback delay ms (flat alias; prefer llm.fallback.llm_fallback_delay_ms)

Example:

500

analysis

object

Post-call analysis (PCA) fields for the agent version

Show child attributes

Response

201 - application/json

Agent created; current_version includes llm.fallback and flat fallback fields

number

required

Example:

0

is_published

boolean

required

Example:

false

llm

object

Show child attributes

fallback_llm_enabled

boolean

Example:

false

llm_fallback_model

string | null

Example:

"llm_abc123xyz789ab"

fall_back_llm_id

string | null

Example:

"llm_abc123xyz789ab"

llm_fallback_delay_ms

number | null

Example:

500

transcriber_id

string | null

Example:

"tr0deepnova3xx"

analysis

object

Show child attributes

List AgentsRetrieve a paginated list of all agents in your organization.

Create a new agent (structured response)

curl --request POST \
  --url https://api.dialnexa.com/agents2 \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-organization-id: <x-organization-id>' \
  --data '
{
  "title": "Customer Support Agent",
  "llm": {
    "id": "llm_xxxxx",
    "settings": {
      "temperature": 0.1,
      "structured_output": true
    },
    "fallback": {
      "fallback_llm_enabled": false,
      "llm_fallback_model": "abc123xyz789ab",
      "fall_back_llm_id": "llm_abc123xyz789ab",
      "llm_fallback_delay_ms": 500
    }
  },
  "fallback_llm_enabled": false,
  "llm_fallback_model": "abc123xyz789ab",
  "llm_fallback_delay_ms": 500,
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "customer_satisfaction",
        "field_type": "NUMBER",
        "field_description": "Customer satisfaction rating"
      }
    ]
  }
}
'

import requests

url = "https://api.dialnexa.com/agents2"

payload = {
    "title": "Customer Support Agent",
    "llm": {
        "id": "llm_xxxxx",
        "settings": {
            "temperature": 0.1,
            "structured_output": True
        },
        "fallback": {
            "fallback_llm_enabled": False,
            "llm_fallback_model": "abc123xyz789ab",
            "fall_back_llm_id": "llm_abc123xyz789ab",
            "llm_fallback_delay_ms": 500
        }
    },
    "fallback_llm_enabled": False,
    "llm_fallback_model": "abc123xyz789ab",
    "llm_fallback_delay_ms": 500,
    "analysis": { "postcall_analysis": [
            {
                "field_name": "customer_satisfaction",
                "field_type": "NUMBER",
                "field_description": "Customer satisfaction rating"
            }
        ] }
}
headers = {
    "x-organization-id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'x-organization-id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Customer Support Agent',
    llm: {
      id: 'llm_xxxxx',
      settings: {temperature: 0.1, structured_output: true},
      fallback: {
        fallback_llm_enabled: false,
        llm_fallback_model: 'abc123xyz789ab',
        fall_back_llm_id: 'llm_abc123xyz789ab',
        llm_fallback_delay_ms: 500
      }
    },
    fallback_llm_enabled: false,
    llm_fallback_model: 'abc123xyz789ab',
    llm_fallback_delay_ms: 500,
    analysis: {
      postcall_analysis: [
        {
          field_name: 'customer_satisfaction',
          field_type: 'NUMBER',
          field_description: 'Customer satisfaction rating'
        }
      ]
    }
  })
};

fetch('https://api.dialnexa.com/agents2', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dialnexa.com/agents2",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'title' => 'Customer Support Agent',
    'llm' => [
        'id' => 'llm_xxxxx',
        'settings' => [
                'temperature' => 0.1,
                'structured_output' => true
        ],
        'fallback' => [
                'fallback_llm_enabled' => false,
                'llm_fallback_model' => 'abc123xyz789ab',
                'fall_back_llm_id' => 'llm_abc123xyz789ab',
                'llm_fallback_delay_ms' => 500
        ]
    ],
    'fallback_llm_enabled' => false,
    'llm_fallback_model' => 'abc123xyz789ab',
    'llm_fallback_delay_ms' => 500,
    'analysis' => [
        'postcall_analysis' => [
                [
                                'field_name' => 'customer_satisfaction',
                                'field_type' => 'NUMBER',
                                'field_description' => 'Customer satisfaction rating'
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "x-organization-id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.dialnexa.com/agents2"

	payload := strings.NewReader("{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-organization-id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dialnexa.com/agents2")
  .header("x-organization-id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dialnexa.com/agents2")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-organization-id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"title\": \"Customer Support Agent\",\n  \"llm\": {\n    \"id\": \"llm_xxxxx\",\n    \"settings\": {\n      \"temperature\": 0.1,\n      \"structured_output\": true\n    },\n    \"fallback\": {\n      \"fallback_llm_enabled\": false,\n      \"llm_fallback_model\": \"abc123xyz789ab\",\n      \"fall_back_llm_id\": \"llm_abc123xyz789ab\",\n      \"llm_fallback_delay_ms\": 500\n    }\n  },\n  \"fallback_llm_enabled\": false,\n  \"llm_fallback_model\": \"abc123xyz789ab\",\n  \"llm_fallback_delay_ms\": 500,\n  \"analysis\": {\n    \"postcall_analysis\": [\n      {\n        \"field_name\": \"customer_satisfaction\",\n        \"field_type\": \"NUMBER\",\n        \"field_description\": \"Customer satisfaction rating\"\n      }\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "number": 0,
  "is_published": false,
  "llm": {
    "id": "llm_xxxxx",
    "settings": {
      "temperature": 0.1,
      "structured_output": true
    },
    "fallback": {
      "fallback_llm_enabled": false,
      "llm_fallback_model": "abc123xyz789ab",
      "fall_back_llm_id": "llm_abc123xyz789ab",
      "llm_fallback_delay_ms": 500
    }
  },
  "fallback_llm_enabled": false,
  "llm_fallback_model": "llm_abc123xyz789ab",
  "fall_back_llm_id": "llm_abc123xyz789ab",
  "llm_fallback_delay_ms": 500,
  "transcriber_id": "tr0deepnova3xx",
  "analysis": {
    "postcall_analysis": [
      {
        "field_name": "customer_satisfaction",
        "field_type": "NUMBER",
        "field_description": "Customer satisfaction rating"
      }
    ]
  }
}

Overview

Endpoints - v1

Endpoints - Legacy

Code Examples And SDK Status

When to use this

Key fields

Pipeline Types

Authorizations

Headers

Body

Response

​When to use this

​Key fields

​Pipeline Types

Authorizations

Headers

Body

Response

When to use this

Key fields

Pipeline Types