Skip to main content

​
Endpoints

MethodPathDescription
GET/v1/agentsList all agents
POST/v1/agentsCreate a new agent
GET/v1/agents/{id}Get agent details
PATCH/v1/agents/{id}Update an agent
DELETE/v1/agents/{id}Delete an agent

​
List Agents

GET /v1/agents
Query parameters:
ParamTypeDescription
modestringFilter by public, private, or commercial
pagenumberPage number (default: 1)
limitnumberItems per page (default: 20, max: 100)
Response: 
{
  "success": true,
  "data": [
    {
      "id": "agent_abc123",
      "name": "Customer Support",
      "mode": "public",
      "agentArchitecture": "pipeline",
      "active": true,
      "createdAt": "2024-01-10T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "total": 5,
    "hasNext": false
  }
}

​
Create Agent

POST /v1/agents

​
Pipeline Architecture

{
  "name": "Sales Bot",
  "agentArchitecture": "pipeline",
  "model": "gpt-4o",
  "stt": "deepgram",
  "tts": "cartesia",
  "voiceId": "some-cartesia-voice-id",
  "systemPrompt": "You are a helpful sales agent for Acme Corp...",
  "language": "en",
  "mode": "private",
  "temperature": 0.7
}

​
Realtime Architecture

{
  "name": "Low Latency Support",
  "agentArchitecture": "realtime",
  "realtimeProvider": "openai",
  "voiceId": "alloy",
  "systemPrompt": "You are a support agent...",
  "language": "en",
  "mode": "public"
}

​
Text Architecture

{
  "name": "Support Chatbot",
  "agentArchitecture": "text",
  "model": "gpt-4o-mini",
  "systemPrompt": "You are a helpful support assistant...",
  "language": "en",
  "mode": "public"
}
Text agents are accessible via the Chat API only. They cannot handle voice calls or phone numbers.

​
Required Fields by Architecture

FieldPipelineRealtimeText
nameRequiredRequiredRequired
agentArchitectureRequiredRequiredRequired
modelRequired—Required
sttRequired——
ttsRequired——
realtimeProvider—Required—
systemPromptRequiredRequiredRequired
Response: 
{
  "success": true,
  "data": {
    "id": "agent_new123",
    "name": "Sales Bot",
    "agentArchitecture": "pipeline",
    "active": false,
    "createdAt": "2024-01-15T10:30:00Z"
  }
}

​
Get Agent

GET /v1/agents/{id}
Response: 
{
  "success": true,
  "data": {
    "id": "agent_abc123",
    "name": "Customer Support",
    "agentArchitecture": "pipeline",
    "model": "gpt-4o",
    "stt": "deepgram",
    "tts": "cartesia",
    "voiceId": "voice_xyz",
    "systemPrompt": "You are a helpful customer support agent...",
    "language": "en",
    "mode": "public",
    "active": true,
    "temperature": 0.7,
    "enabledFunctions": ["web_search"],
    "enabledCustomFunctions": ["check_order_status"],
    "createdAt": "2024-01-10T09:00:00Z",
    "updatedAt": "2024-01-14T15:20:00Z"
  }
}

​
Update Agent

PATCH /v1/agents/{id}
Send only the fields you want to update: 
{
  "systemPrompt": "Updated instructions...",
  "temperature": 0.5,
  "active": true
}
Only org owners/admins can update public or commercial agents. The agent creator can update their own private agents.

​
Delete Agent

DELETE /v1/agents/{id}
Response: 
{
  "success": true,
  "data": {
    "message": "Agent deleted successfully"
  }
}
Deleting an agent is permanent. Associated call logs and transcripts are retained for billing purposes, but the agent configuration is removed.