Create Agent

POST

api

create-agent

curl -X POST https://api.vaanivoice.ai/api/create-agent \
  -H "X-API-Key: vaani_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_display_name": "support-bot",
    "config": {
      "persona": {
        "identity": {
          "system_prompt": "You are a helpful customer support agent."
        }
      }
    }
  }'

const response = await fetch("https://api.vaanivoice.ai/api/create-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "vaani_<your_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_display_name: "support-bot",
    config: {
      persona: {
        identity: {
          system_prompt: "You are a helpful customer support agent.",
        },
      },
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.vaanivoice.ai/api/create-agent",
    headers={
        "X-API-Key": "vaani_<your_key>",
        "Content-Type": "application/json",
    },
    json={
        "agent_display_name": "support-bot",
        "config": {
            "persona": {
                "identity": {
                    "system_prompt": "You are a helpful customer support agent."
                }
            }
        },
    },
)
print(response.json())

{
  "agent_id": "7ec4155e-0e62-440a-b983-5974f7697854",
  "client_id": "9abf5eff-e978-4e87-954d-7ff6ba570796",
  "user_id": "4f1c2a7e-8b3d-4c55-9e0a-1d2b3c4d5e6f",
  "agent_display_name": "support-bot",
  "last_edited_at": "2026-11-03T12:56:11.433169",
  "published_at": null,
  "persona": { "...": "..." },
  "training": { "...": "..." },
  "experience": { "...": "..." },
  "analysis": { "...": "..." },
  "deployment_config": {},
  "warnings": []
}

Create a new agent and associate it with the authenticated user’s client. The client_id is automatically extracted from your API key - you don’t need to supply it.

Parameters

string

required

Human-readable name for the agent (e.g. "support-bot")

object

default:"{}"

Optional initial configuration for the agent. You can pass any subset of the agent config sections here or leave it empty and configure them later via the section PATCH endpoints.

Show config structure

object

Persona section - identity, senses/capabilities, actions, memories.

object

Training section - knowledge base (RAG), FAQ, guardrails.

object

Experience section - conversational feel, call settings.

object

Analysis section - dispositions, data extraction.

object

Deployment section - phone call-type routing.

Request Example

curl -X POST https://api.vaanivoice.ai/api/create-agent \
  -H "X-API-Key: vaani_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_display_name": "support-bot",
    "config": {
      "persona": {
        "identity": {
          "system_prompt": "You are a helpful customer support agent."
        }
      }
    }
  }'

const response = await fetch("https://api.vaanivoice.ai/api/create-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "vaani_<your_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_display_name: "support-bot",
    config: {
      persona: {
        identity: {
          system_prompt: "You are a helpful customer support agent.",
        },
      },
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.vaanivoice.ai/api/create-agent",
    headers={
        "X-API-Key": "vaani_<your_key>",
        "Content-Type": "application/json",
    },
    json={
        "agent_display_name": "support-bot",
        "config": {
            "persona": {
                "identity": {
                    "system_prompt": "You are a helpful customer support agent."
                }
            }
        },
    },
)
print(response.json())

Response

{
  "agent_id": "7ec4155e-0e62-440a-b983-5974f7697854",
  "client_id": "9abf5eff-e978-4e87-954d-7ff6ba570796",
  "user_id": "4f1c2a7e-8b3d-4c55-9e0a-1d2b3c4d5e6f",
  "agent_display_name": "support-bot",
  "last_edited_at": "2026-11-03T12:56:11.433169",
  "published_at": null,
  "persona": { "...": "..." },
  "training": { "...": "..." },
  "experience": { "...": "..." },
  "analysis": { "...": "..." },
  "deployment_config": {},
  "warnings": []
}

The response is the full agent configuration as it was saved, not a short confirmation. It has no success flag and no agent_name field; read agent_id from the top level and agent_display_name for the name. The example above is abbreviated - the section objects are returned in full.

string

UUID of the newly created agent. Use this in subsequent PATCH calls and when triggering calls.

string

Client UUID the agent was associated with (resolved from your API key).

string

UUID of the user that owns the API key.

string

Display name you supplied for the agent.

object

The saved configuration sections, with defaults filled in for anything you did not send.

string[]

Non-fatal notes about the supplied config, if any.

Duplicate name (409)

Agent names are unique within your workspace. Creating an agent whose agent_display_name already exists returns 409 Conflict:

{
  "status_code": 409,
  "error": "Conflict",
  "message": "Agent with name 'vghjkmnqaprobe5c1ae1' already exists",
  "code": "HTTP_409_ERROR",
  "path": "/api/create-agent",
  "timestamp": "2026-11-05T08:05:43.330595Z",
  "request_id": "1b87fdf0-401e-4e35-8660-cb144e89723d"
}

Video Walkthrough

curl -X POST https://api.vaanivoice.ai/api/create-agent \
  -H "X-API-Key: vaani_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_display_name": "support-bot",
    "config": {
      "persona": {
        "identity": {
          "system_prompt": "You are a helpful customer support agent."
        }
      }
    }
  }'

const response = await fetch("https://api.vaanivoice.ai/api/create-agent", {
  method: "POST",
  headers: {
    "X-API-Key": "vaani_<your_key>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_display_name: "support-bot",
    config: {
      persona: {
        identity: {
          system_prompt: "You are a helpful customer support agent.",
        },
      },
    },
  }),
});

const data = await response.json();
console.log(data);

import requests

response = requests.post(
    "https://api.vaanivoice.ai/api/create-agent",
    headers={
        "X-API-Key": "vaani_<your_key>",
        "Content-Type": "application/json",
    },
    json={
        "agent_display_name": "support-bot",
        "config": {
            "persona": {
                "identity": {
                    "system_prompt": "You are a helpful customer support agent."
                }
            }
        },
    },
)
print(response.json())

{
  "agent_id": "7ec4155e-0e62-440a-b983-5974f7697854",
  "client_id": "9abf5eff-e978-4e87-954d-7ff6ba570796",
  "user_id": "4f1c2a7e-8b3d-4c55-9e0a-1d2b3c4d5e6f",
  "agent_display_name": "support-bot",
  "last_edited_at": "2026-11-03T12:56:11.433169",
  "published_at": null,
  "persona": { "...": "..." },
  "training": { "...": "..." },
  "experience": { "...": "..." },
  "analysis": { "...": "..." },
  "deployment_config": {},
  "warnings": []
}

Overview

Campaigns

Agents

Calls

Create Agent

Create Agent

Parameters

Request Example

Response

Duplicate name (409)

Video Walkthrough

​Create Agent

​Parameters

​Request Example

​Response

​Duplicate name (409)

​Video Walkthrough

Create Agent

Parameters

Request Example

Response

Duplicate name (409)

Video Walkthrough