Skip to main content
POST
/
agent
Error
A valid request URL is required to generate request examples
{
  "id": "<string>",
  "name": "<string>",
  "user_id": "<string>",
  "org_id": "<string>",
  "description": "<string>",
  "model_provider": "<string>",
  "model_name": "<string>",
  "system_prompt": "<string>",
  "temperature": 123,
  "max_tokens": 123,
  "first_message": "<string>",
  "first_message_mode": "<string>",
  "voice_provider": "<string>",
  "voice_id": "<string>",
  "voice_model": "<string>",
  "voice_stability": 123,
  "voice_similarity": 123,
  "voice_speed": 123,
  "transcriber_provider": "<string>",
  "transcriber_model": "<string>",
  "transcriber_language": "<string>",
  "background_sound": "<string>",
  "background_sound_url": "<string>",
  "max_duration": 123,
  "silence_timeout": 123,
  "enable_end_call": true,
  "voicemail_detection": true,
  "voicemail_message": "<string>",
  "server_url": "<string>",
  "tool_ids": [
    "<unknown>"
  ],
  "rag_enabled": true,
  "rag_config": {},
  "status": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>",
  "deleted_at": "<string>",
  "hipaa_compliance": true,
  "audio_recording": true,
  "logging": true,
  "transcript_enabled": true
}

Authorizations

X-API-Key
string
header
required

Body

application/json

Create a new AI agent.

Only name and system_prompt are required. All other fields default to the same values as the database defaults so callers can omit them.

name
string
required

Agent display name

Required string length: 1 - 100
system_prompt
string
required

System prompt for the LLM

description
string | null

Optional description of the agent

model_provider
string
default:openai

LLM provider (e.g. 'openai', 'anthropic')

model_name
string
default:gpt-4o-mini-cluster

Model identifier

temperature
number
default:0.5

LLM sampling temperature

Required range: 0 <= x <= 2
max_tokens
integer
default:250

Max tokens per LLM response

Required range: 1 <= x <= 8192
first_message
string | null

Opening message spoken by the agent

first_message_mode
string
default:agent_speaks_first

Who speaks first: 'agent_speaks_first' or 'user_speaks_first'

voice_provider
string
default:11labs

TTS provider

voice_id
string | null

Provider-specific voice identifier

voice_model
string
default:eleven_turbo_v2_5

Voice model identifier

voice_stability
number
default:0.5
Required range: 0 <= x <= 1
voice_similarity
number
default:0.75
Required range: 0 <= x <= 1
voice_speed
number
default:1
Required range: 0.5 <= x <= 2
transcriber_provider
string
default:deepgram

STT provider

transcriber_model
string
default:nova-3

STT model identifier

transcriber_language
string
default:en

BCP-47 language code

background_sound
string
default:office

Preset background sound name

background_sound_url
string | null

Custom background audio URL

max_duration
integer
default:600

Maximum call duration in seconds

Required range: 10 <= x <= 43200
silence_timeout
integer
default:30

Silence timeout in seconds

Required range: 5 <= x <= 300
enable_end_call
boolean | null

Allow agent to end the call

voicemail_detection
boolean | null

Enable voicemail detection

voicemail_message
string | null

Message to leave on voicemail

server_url
string | null

Webhook URL for server-side events

tool_ids
any[]

Tool IDs to attach to the agent

rag_enabled
boolean | null

Enable retrieval-augmented generation

rag_config
Rag Config · object

RAG configuration object

hipaa_compliance
boolean | null

Enable HIPAA compliance mode

audio_recording
boolean | null

Record audio for this agent

logging
boolean | null

Enable call logging

transcript_enabled
boolean | null

Save call transcripts

Response

Successful Response

Full agent object returned by the API.

id
string
required
name
string
required
user_id
string | null
org_id
string | null
description
string | null
model_provider
string | null
model_name
string | null
system_prompt
string | null
temperature
number | null
max_tokens
integer | null
first_message
string | null
first_message_mode
string | null
voice_provider
string | null
voice_id
string | null
voice_model
string | null
voice_stability
number | null
voice_similarity
number | null
voice_speed
number | null
transcriber_provider
string | null
transcriber_model
string | null
transcriber_language
string | null
background_sound
string | null
background_sound_url
string | null
max_duration
integer | null
silence_timeout
integer | null
enable_end_call
boolean | null
voicemail_detection
boolean | null
voicemail_message
string | null
server_url
string | null
tool_ids
any[] | null
rag_enabled
boolean | null
rag_config
Rag Config · object
status
string | null
created_at
string | null
updated_at
string | null
deleted_at
string | null
hipaa_compliance
boolean | null
audio_recording
boolean | null
logging
boolean | null
transcript_enabled
boolean | null