Introduction
Agent API
Agent Tool API
Widget Settings API
Phone Number & Telephony API
- GETList Available Numbers
- POSTBuy Phone Number
- DELRelease Phone Number
- GETList Purchased Numbers
- POSTImport Phone Number
- GETList Imported Numbers
- GETGet Imported Number
- PUTUpdate Imported Number
- DELDelete Imported Number
- GETList Twilio Owned Numbers
- POSTAdd Twilio Number
- POSTCreate Telephony Type
- GETGet Selected Telephony
Campaign API
Contact API
Appointment API
Cal.com Integration API
RAG Knowledge Base API
Webhooks
Health API
curl https://api.ravan.ai/api/v1/agents/?limit=10&offset=0 \
-H "X-Api-Key: YOUR_API_KEY"
{
"success": true,
"message": "Agents fetched 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",
"s2s_model": "gpt-4o-realtime",
"voice_id": "alloy",
"temperature": 0.7,
"reminder_trigger_ms": 8000,
"reminder_max_count": 2,
"ambient_sound": "office",
"ambient_sound_volume": 0.15,
"end_call_after_silence": true,
"max_call_duration_ms": 600000,
"ring_duration_ms": 30000,
"enable_voicemail_detection": true,
"voicemail_message": "Hi, this is Ava from Acme Corp. Please call us back at your convenience.",
"voicemail_detection_timeout_ms": 10000,
"ivr_options": null,
"post_call_analysis_model": "gpt-4o",
"analysis_summary_prompt": "Summarize the key points, action items, and customer sentiment from this call.",
"selected_tools": [],
"integrations": null,
"knowledge_base": "",
"begin_message": "Hello! This is Ava from Acme Corp. How can I help you today?",
"start_speaker": "agent",
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T14:15:00Z"
}
],
"meta": {
"total": 1,
"limit": 10,
"offset": 0
}
}
Agent API
List Agents
Retrieve a paginated list of all voice AI agents in your organization.
GET
/
api
/
v1
/
agents
curl https://api.ravan.ai/api/v1/agents/?limit=10&offset=0 \
-H "X-Api-Key: YOUR_API_KEY"
{
"success": true,
"message": "Agents fetched 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",
"s2s_model": "gpt-4o-realtime",
"voice_id": "alloy",
"temperature": 0.7,
"reminder_trigger_ms": 8000,
"reminder_max_count": 2,
"ambient_sound": "office",
"ambient_sound_volume": 0.15,
"end_call_after_silence": true,
"max_call_duration_ms": 600000,
"ring_duration_ms": 30000,
"enable_voicemail_detection": true,
"voicemail_message": "Hi, this is Ava from Acme Corp. Please call us back at your convenience.",
"voicemail_detection_timeout_ms": 10000,
"ivr_options": null,
"post_call_analysis_model": "gpt-4o",
"analysis_summary_prompt": "Summarize the key points, action items, and customer sentiment from this call.",
"selected_tools": [],
"integrations": null,
"knowledge_base": "",
"begin_message": "Hello! This is Ava from Acme Corp. How can I help you today?",
"start_speaker": "agent",
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T14:15:00Z"
}
],
"meta": {
"total": 1,
"limit": 10,
"offset": 0
}
}
Authorizations
Your Agni API key. Find it in your support@ravan.ai under Settings → API Keys.
Query Parameters
Maximum number of agents to return per page. Defaults to all agents if not specified.
Number of records to skip for pagination. Defaults to
0.Response
Whether the request succeeded.
Human-readable status message.
Array of agent objects.
Show data[]
Show data[]
Unique agent ID (UUID).
ID of the organization that owns this agent.
ID of the widget settings associated with this agent.
Internal name used to identify the agent in your dashboard.
Display name shown to end users during calls.
Current agent status. Allowed values:
AGENT_STATUS_UNSPECIFIED, AGENT_STATUS_ACTIVE, AGENT_STATUS_INACTIVE.LLM model identifier used for conversation (e.g.
gpt-4o, gpt-4o-mini).Speech-to-speech model identifier for real-time voice processing.
Voice profile ID used for text-to-speech output.
LLM temperature (0.0–1.0). Lower values produce more deterministic responses.
Milliseconds of silence before the agent sends a reminder prompt.
Maximum number of reminder prompts the agent will send per call.
Background ambient sound identifier (e.g.
office, cafe).Volume level for ambient sound, from
0.0 (silent) to 1.0 (full).Whether to automatically end the call after prolonged silence.
Maximum allowed call duration in milliseconds before auto-disconnect.
How long the phone rings (in ms) before the call is considered unanswered.
Whether the agent should detect voicemail greetings and respond accordingly.
Message the agent leaves when voicemail is detected.
Milliseconds to wait before concluding the call reached voicemail.
Interactive Voice Response (IVR) menu configuration for inbound call routing.
LLM model used to generate post-call analysis and summaries.
Custom prompt template used for generating the post-call summary.
Map of tool IDs enabled for this agent during calls.
Third-party integration configuration (e.g. GHL calendar ID, webhook URLs).
Knowledge base content or reference ID that provides context to the agent.
Opening greeting message the agent speaks at the start of each call.
Who speaks first when the call connects —
"agent" or "user".ISO 8601 timestamp when the agent was created.
ISO 8601 timestamp when the agent was last modified.
curl https://api.ravan.ai/api/v1/agents/?limit=10&offset=0 \
-H "X-Api-Key: YOUR_API_KEY"
{
"success": true,
"message": "Agents fetched 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",
"s2s_model": "gpt-4o-realtime",
"voice_id": "alloy",
"temperature": 0.7,
"reminder_trigger_ms": 8000,
"reminder_max_count": 2,
"ambient_sound": "office",
"ambient_sound_volume": 0.15,
"end_call_after_silence": true,
"max_call_duration_ms": 600000,
"ring_duration_ms": 30000,
"enable_voicemail_detection": true,
"voicemail_message": "Hi, this is Ava from Acme Corp. Please call us back at your convenience.",
"voicemail_detection_timeout_ms": 10000,
"ivr_options": null,
"post_call_analysis_model": "gpt-4o",
"analysis_summary_prompt": "Summarize the key points, action items, and customer sentiment from this call.",
"selected_tools": [],
"integrations": null,
"knowledge_base": "",
"begin_message": "Hello! This is Ava from Acme Corp. How can I help you today?",
"start_speaker": "agent",
"created_at": "2026-03-20T10:30:00Z",
"updated_at": "2026-03-20T14:15:00Z"
}
],
"meta": {
"total": 1,
"limit": 10,
"offset": 0
}
}
⌘I