POST

Create Agent

Creates a new AI Agent in the specified sub-account.

POSThttps://api.vantaxai.com/v1/agents

Only `name` is required. Every other field has a sensible default — you can fully configure voice, model, knowledge base, calendar, and call behavior at creation time or update later.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…
Content-Typestringrequired
Must be application/json for requests with a body.
example: application/json

Body Parameters

namestringrequired
Display name of the Agent.
example: Front Desk Agent
sub_account_idstringrequired
Sub-account that will own the Agent.
example: sub_8a1f4c2e
descriptionstringoptional
Internal description of the Agent's purpose.
system_promptstringoptional
The Agent's core instructions / persona.
voice_idstringoptional
Voice used for phone calls. See List Voices.
example: voice_aria
knowledgebase_idstringoptional
Knowledge base the Agent can reference.
calendar_idstringoptional
Default calendar for booking appointments.
ai_modelstringoptional
LLM powering the Agent.
gpt-4ogpt-4o-miniclaude-3-5-sonnet
example: gpt-4o
temperaturenumberoptional
Sampling temperature 0–2. Defaults to 0.7.
languagestringoptional
BCP-47 language tag.
example: en-US
is_activebooleanoptional
Whether the Agent is live. Defaults to true.
recordingbooleanoptional
Record calls handled by this Agent.
max_call_timeintegeroptional
Maximum call duration in seconds.

Request

curl -X POST https://api.vantaxai.com/v1/agents \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Front Desk Agent",
    "sub_account_id": "sub_8a1f4c2e",
    "voice_id": "voice_aria",
    "ai_model": "gpt-4o",
    "language": "en-US"
  }'

const res = await fetch("https://api.vantaxai.com/v1/agents", {
  method: "POST",
  headers: {
    Authorization: "Bearer vx_live_3fa9c2...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Front Desk Agent",
    sub_account_id: "sub_8a1f4c2e",
    voice_id: "voice_aria",
    ai_model: "gpt-4o",
  }),
});
const { data: agent } = await res.json();

const agent = await vantax.agents.create({
  name: "Front Desk Agent",
  subAccountId: "sub_8a1f4c2e",
  voiceId: "voice_aria",
  aiModel: "gpt-4o",
});

agent = vantax.agents.create(
    name="Front Desk Agent",
    sub_account_id="sub_8a1f4c2e",
    voice_id="voice_aria",
    ai_model="gpt-4o",
)

Response

{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "id": "agt_3d9b21",
    "name": "Front Desk Agent",
    "description": null,
    "voice_id": "voice_aria",
    "knowledgebase_id": null,
    "calendar_id": null,
    "ai_model": "gpt-4o",
    "temperature": 0.7,
    "language": "en-US",
    "is_active": true,
    "created_at": "2026-01-14T10:30:00Z"
  }
}

{
  "success": false,
  "message": "Validation failed",
  "errors": [
    { "field": "name", "message": "name is required" }
  ]
}