Create a new XUNA AI Conversational AI voice agent

The create agent endpoint provisions a new voice agent and returns its agent_id. You pass the agent ID to start conversations, assign phone numbers, or launch batch calls.

Endpoint

POST https://api.xuna.ai/v1/convai/agents

Request parameters

string

required

A human-readable label for the agent. Shown in the dashboard and in list responses.

string[]

Optional tags for organising agents. Useful for filtering in the dashboard.

object

Agent behaviour and voice settings.

Show conversation_config properties

object

Text-to-speech configuration.

Show tts properties

string

required

The XUNA AI voice ID to use for the agent’s speech.

string

The TTS model to use. Defaults to xuna_flash_v2 for low-latency responses.

object

Conversation behaviour settings.

Show agent properties

string

The opening line the agent speaks when a conversation starts.

object

System prompt configuration.

Show prompt properties

string

The system prompt text that defines the agent’s persona, goals, and constraints.

Example request

from xuna_ai.client import XunaAI

client = XunaAI(api_key="YOUR_API_KEY")

response = client.conversational_ai.agents.create(
    name="My voice agent",
    tags=["test"],
    conversation_config={
        "tts": {
            "voice_id": "aMSt68OGf4xUZAnLpTU8",
            "model_id": "xuna_flash_v2",
        },
        "agent": {
            "first_message": "Hi, how can I help you today?",
            "prompt": {
                "prompt": "You are a helpful assistant.",
            },
        },
    },
)

print("Agent ID:", response.agent_id)

import { XunaAIClient } from "@xuna-ai/xuna-ai-js";

const client = new XunaAIClient({ apiKey: "YOUR_API_KEY" });

const agent = await client.conversationalAi.agents.create({
    name: "My voice agent",
    tags: ["test"],
    conversationConfig: {
        tts: {
            voiceId: "aMSt68OGf4xUZAnLpTU8",
            modelId: "xuna_flash_v2",
        },
        agent: {
            firstMessage: "Hi, how can I help you today?",
            prompt: {
                prompt: "You are a helpful assistant.",
            },
        },
    },
});

console.log("Agent ID:", agent.agentId);

curl -X POST https://api.xuna.ai/v1/convai/agents \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My voice agent",
    "tags": ["test"],
    "conversation_config": {
      "tts": {
        "voice_id": "aMSt68OGf4xUZAnLpTU8",
        "model_id": "xuna_flash_v2"
      },
      "agent": {
        "first_message": "Hi, how can I help you today?",
        "prompt": {
          "prompt": "You are a helpful assistant."
        }
      }
    }
  }'

Response

{
  "agent_id": "agent_7101k5zvyjhmfg983brhmhkd98n6"
}

string

required

The unique identifier for the newly created agent. Store this value — you need it to start conversations, update the agent, or assign a phone number.

After creating an agent you can update any part of its configuration at any time using the PATCH endpoint.

Overview

Agents

Telephony

Create a new XUNA AI Conversational AI voice agent

Endpoint

Request parameters

Example request

Response

​Endpoint

​Request parameters

​Example request

​Response

Endpoint

Request parameters

Example request

Response