POST
/
api
/
v1
/
agents
curl -X POST https://api.ravan.ai/api/v1/agents/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_settings_id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "name": "Sales Assistant",
    "agent_name": "Ava",
    "model": "gpt-4o",
    "temperature": 0.7,
    "begin_message": "Hello! This is Ava. How can I help you today?",
    "start_speaker": "agent"
  }'

{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "id": "019d1fdb-98e9-7c87-86c7-321e2fa98733",
    "organization_id": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e",
    "widget_settings_id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "name": "Sales Assistant",
    "agent_name": "Ava",
    "status": "AGENT_STATUS_ACTIVE",
    "model": "gpt-4o",
    "temperature": 0.7,
    "selected_tools": [],
    "integrations": null,
    "begin_message": "Hello! This is Ava. How can I help you today?",
    "start_speaker": "agent",
    "created_at": "2026-03-20T10:30:00Z",
    "updated_at": "2026-03-20T10:30:00Z"
  }
}

​
Authorizations

​
X-Api-Key
string
required
Your Agni API key. Find it in your support@ravan.ai under Settings → API Keys.

​
Body

​
widget_settings_id
string
UUID of the widget settings to associate with this agent. Create widget settings first via the Widget Settings API.
​
name
string
Internal name for the agent, visible in your dashboard.
​
agent_name
string
Display name shown to end users during calls and in the widget.
​
model
string
LLM model identifier for agent conversation (e.g. gpt-4o, gpt-4o-mini).
​
s2s_model
string
Speech-to-speech model identifier for real-time voice processing.
​
voice_id
string
Voice profile ID for text-to-speech output (e.g. alloy, nova, shimmer).
​
temperature
number
LLM temperature from 0.0 to 1.0. Lower values produce more focused, deterministic responses. Default: 0.7.
​
reminder_trigger_ms
integer
Milliseconds of silence before the agent sends a follow-up reminder (e.g. 8000 for 8 seconds).
​
reminder_max_count
integer
Maximum number of reminders the agent sends per call before stopping.
​
ambient_sound
string
Background ambient sound to play during calls (e.g. office, cafe).
​
ambient_sound_volume
number
Volume level for ambient sound, from 0.0 (silent) to 1.0 (full volume).
​
end_call_after_silence
boolean
If true, the agent automatically ends the call after prolonged user silence.
​
max_call_duration_ms
integer
Maximum call duration in milliseconds. The call auto-disconnects after this limit (e.g. 600000 for 10 minutes).
​
ring_duration_ms
integer
How long to ring before marking the call as unanswered (in milliseconds).
​
enable_voicemail_detection
boolean
If true, the agent detects voicemail greetings and leaves a message instead of continuing the conversation.
​
voicemail_message
string
The message the agent speaks when voicemail is detected.
​
voicemail_detection_timeout_ms
integer
Milliseconds to wait for speech before classifying the call as voicemail.
​
ivr_options
object
IVR (Interactive Voice Response) menu configuration for inbound call routing.
​
post_call_analysis_model
string
LLM model used for post-call analysis (e.g. gpt-4o).
​
analysis_summary_prompt
string
Custom prompt for generating the post-call summary and analysis.
​
selected_tools
object
Tool IDs to enable for this agent. Tools must be created first via the Agent Tool API.
​
integrations
object
Third-party integration configuration (e.g. calendar IDs, CRM references).
​
knowledge_base
string
Knowledge base content or reference that gives the agent domain-specific context.
​
begin_message
string
Opening greeting the agent speaks when the call starts.
​
start_speaker
string
Who speaks first: "agent" (agent greets the user) or "user" (agent waits for the user).

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Human-readable status message.
​
data
object
The newly created agent object.
curl -X POST https://api.ravan.ai/api/v1/agents/ \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "widget_settings_id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "name": "Sales Assistant",
    "agent_name": "Ava",
    "model": "gpt-4o",
    "temperature": 0.7,
    "begin_message": "Hello! This is Ava. How can I help you today?",
    "start_speaker": "agent"
  }'

{
  "success": true,
  "message": "Agent created successfully",
  "data": {
    "id": "019d1fdb-98e9-7c87-86c7-321e2fa98733",
    "organization_id": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e",
    "widget_settings_id": "019d1fdb-6701-762d-97bd-93fc72606d7c",
    "name": "Sales Assistant",
    "agent_name": "Ava",
    "status": "AGENT_STATUS_ACTIVE",
    "model": "gpt-4o",
    "temperature": 0.7,
    "selected_tools": [],
    "integrations": null,
    "begin_message": "Hello! This is Ava. How can I help you today?",
    "start_speaker": "agent",
    "created_at": "2026-03-20T10:30:00Z",
    "updated_at": "2026-03-20T10:30:00Z"
  }
}

Authorizations

​
X-Api-Key
string
header
required

Body

application/json
​
widget_settings_id
string
​
name
string
​
agent_name
string
​
model
string
​
s2s_model
string
​
voice_id
string
​
temperature
number<double>
​
reminder_trigger_ms
integer<int32>
​
reminder_max_count
integer<int32>
​
ambient_sound
string
​
ambient_sound_volume
number<double>
​
end_call_after_silence
boolean
​
max_call_duration_ms
integer<int32>
​
ring_duration_ms
integer<int32>
​
enable_voicemail_detection
boolean
​
voicemail_message
string
​
voicemail_detection_timeout_ms
integer<int32>
​
ivr_options
object
​
post_call_analysis_model
string
​
analysis_summary_prompt
string
​
selected_tools
object
​
integrations
object
​
knowledge_base
string
​
begin_message
string
​
start_speaker
string

Response

Successful response

​
success
boolean
​
message
string
​
data
object