Skip to main content
POST
/
api
/
agents
{
  "agent_name": "Sales Rep",
  "stt_provider": "deepgram",
  "tts_provider": "elevenlabs",
  "tts_voice": "21m00Tcm4TlvDq8ikWAM",
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "system_prompt": "You are a helpful sales representative...",
  "language": "EN",
  "speak_first": true,
  "recording_enabled": true
}

{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "agent_id": "agent_a1b2c3d4e5f6",
    "agent_name": "Sales Rep",
    "language": "EN",
    "stt_provider": "deepgram",
    "tts_provider": "elevenlabs",
    "tts_voice": "21m00Tcm4TlvDq8ikWAM",
    "llm_provider": "openai",
    "llm_model": "gpt-4o",
    "system_prompt": "You are a helpful sales representative...",
    "speak_first": true,
    "end_call_tool": false,
    "llm_temperature": 0.7,
    "recording_enabled": true,
    "voicemail_detection": false,
    "voicemail_response_delay": 2.0,
    "custom_tools": [],
    "kb_document_ids": [],
    "assigned_phone_number_ids": [],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
Create a new AI voice agent with specific configuration for STT, TTS, LLM, and behavior.

​
Headers

​
X-API-Key
string
required
Your API key for authentication.
​
X-Organization-Id
string
required
The organization ID.
​
Content-Type
string
required
Must be application/json.

​
Permissions

  • agents:create (admin, agent_manager)

​
Request Body

​
agent_name
string
required
The name of the agent (1-100 characters).
​
stt_provider
string
required
Speech-to-Text provider (e.g., deepgram, deepgram-nova-3, aws).
​
tts_provider
string
required
Text-to-Speech provider (e.g., elevenlabs, cartesia, deepgram).
​
tts_voice
string
required
Voice ID for the selected TTS provider.
​
llm_provider
string
required
LLM provider (e.g., openai, anthropic, google).
​
llm_model
string
required
Model ID (e.g., gpt-4o, gemini-2.5-flash-lite).
​
system_prompt
string
required
The system prompt that defines the agent’s persona and instructions (10-10000 characters).
​
language
string
default:"EN"
Primary language for the agent (e.g., EN, ES).
​
speak_first
boolean
default:"false"
Whether the agent should speak first when the call connects.
​
end_call_tool
boolean
default:"false"
Enable the built-in end call tool for the agent.
​
llm_temperature
number
default:"0.7"
Temperature setting for the LLM (0.0 to 2.0).
​
llm_fallback_provider
string
Fallback LLM provider when primary fails.
​
llm_fallback_model
string
Fallback LLM model when primary fails.
​
recording_enabled
boolean
default:"false"
Enable call recording for this agent.
​
voicemail_detection
boolean
default:"false"
Enable AMD (Answering Machine Detection).
​
voicemail_message
string
Message to leave if a voicemail is detected.
​
voicemail_response_delay
number
default:"2.0"
Delay in seconds before speaking the voicemail message (1.0-5.0).
​
custom_tools
array
List of custom tool IDs to attach to this agent.
​
kb_document_ids
array
List of knowledge base document IDs to attach to this agent.
​
assigned_phone_number_ids
array
List of phone number IDs to assign to this agent.

​
Response

​
success
boolean
Indicates if the request was successful.
​
message
string
Human-readable success message.
​
data
object
The created agent object (AgentData).
{
  "agent_name": "Sales Rep",
  "stt_provider": "deepgram",
  "tts_provider": "elevenlabs",
  "tts_voice": "21m00Tcm4TlvDq8ikWAM",
  "llm_provider": "openai",
  "llm_model": "gpt-4o",
  "system_prompt": "You are a helpful sales representative...",
  "language": "EN",
  "speak_first": true,
  "recording_enabled": true
}

{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "agent_id": "agent_a1b2c3d4e5f6",
    "agent_name": "Sales Rep",
    "language": "EN",
    "stt_provider": "deepgram",
    "tts_provider": "elevenlabs",
    "tts_voice": "21m00Tcm4TlvDq8ikWAM",
    "llm_provider": "openai",
    "llm_model": "gpt-4o",
    "system_prompt": "You are a helpful sales representative...",
    "speak_first": true,
    "end_call_tool": false,
    "llm_temperature": 0.7,
    "recording_enabled": true,
    "voicemail_detection": false,
    "voicemail_response_delay": 2.0,
    "custom_tools": [],
    "kb_document_ids": [],
    "assigned_phone_number_ids": [],
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}