Create agent

curl --request POST \
  --url http://localhost:8787/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "http://localhost:8787/api/v1/agents"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('http://localhost:8787/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

POST

agents

Create agent

curl --request POST \
  --url http://localhost:8787/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>"
}
'

import requests

url = "http://localhost:8787/api/v1/agents"

payload = { "name": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>'})
};

fetch('http://localhost:8787/api/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

Creates a minimal agent from a persona. The prompt, voice, and other behavior settings are configured afterward via Patch update agent.

Body parameters

string

required

Agent display name, 1–120 characters. This is the only required field

string

Channel the agent serves — one of VOICE, CHAT, WHATSAPP, SMS

string

A persona ID to initialize the agent with — list available personas via GET /prompts/personas.

string

System prompt driving the agent’s behavior and personality.

string

LLM model UUID to run the agent on — list available LLM models & providers via GET /llm/models.

string

Agent description or internal notes.

string

Voice profile UUID, for VOICE agents — list available voices via GET /voices.

string

Knowledge base UUID to ground the agent’s answers in.

boolean

default:"true"

Whether the agent speaks first upon connection.

string

default:"Hello"

Opening line when greet is enabled.

boolean

default:"false"

Whether calls handled by this agent are recorded.

boolean

default:"true"

Whether the agent is active.

curl -X POST https://api.agentic-os.com/api/v1/agents \
  -H "Authorization: Bearer $AGENTIC_OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Voice Agent",
    "channel": "VOICE",
    "agent_persona_id": "c7a840e6-...",
    "llm_model_id": "b9d311f2-...",
    "agent_prompt": "You are a friendly sales representative. Qualify leads concisely.",
    "greet": true,
    "greetMessage": "Hello! Thanks for reaching out. How can I help you today?",
    "is_active": true
  }'

requests.post(
    "https://api.agentic-os.com/api/v1/agents",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "name": "Sales Voice Agent",
        "channel": "VOICE",
        "agent_persona_id": "c7a840e6-...",
        "llm_model_id": "b9d311f2-...",
        "agent_prompt": "You are a friendly sales representative. Qualify leads concisely.",
        "greet": True,
        "greetMessage": "Hello! Thanks for reaching out. How can I help you today?",
        "is_active": True,
    },
)

await fetch("https://api.agentic-os.com/api/v1/agents", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales Voice Agent",
    channel: "VOICE",
    agent_persona_id: "c7a840e6-...",
    llm_model_id: "b9d311f2-...",
    agent_prompt: "You are a friendly sales representative. Qualify leads concisely.",
    greet: true,
    greetMessage: "Hello! Thanks for reaching out. How can I help you today?",
    is_active: true,
  }),
});

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Agent",
  "is_active": true
}

The response’s id is the agent’s channel id, used for most endpoints (calls, campaigns, patching). Some endpoints — like generating a prompt — use the agent’s underlying brain id instead, returned as agent_id or brain.id on this same response.

⌘I

Overview

Account

Integrations

Configuration

Agents

Numbers

Calls

Campaigns

Knowledge Bases

WhatsApp

Logs

Analytics

Create agent

Body parameters

Response

​Body parameters

​Response

Body parameters

Response