​
Base URL

All API requests are made to: 
https://api.ravan.ai

​
Authentication

Authenticate every request by passing your API key in the X-Api-Key header.
Get your API key from the support@ravan.ai under Settings → API Keys.
curl https://api.ravan.ai/api/v1/agents/ \
  -H "X-Api-Key: YOUR_API_KEY"

​
Request Format

  • All request bodies must be JSON with Content-Type: application/json.
  • IDs are UUID v7 strings (e.g. 019d1fdb-3977-7bd5-ab27-8d3b37ddf4fc).
  • Phone numbers must use E.164 format (e.g. +14155550100).
  • Timestamps are returned in ISO 8601 UTC (e.g. 2026-03-20T14:00:00Z).

​
Response Format

Every endpoint returns a consistent JSON envelope: 
{
  "success": true,
  "message": "Human-readable status message",
  "data": { }
}
List endpoints also include a meta object for pagination: 
{
  "success": true,
  "message": "Agents fetched successfully",
  "data": [],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

​
Error Handling

Failed requests return "success": false with an error structure: 
{
  "success": false,
  "message": "Descriptive error message",
  "error": {
    "code": "ERROR_CODE",
    "message": "Detailed explanation",
    "details": {}
  }
}
HTTP StatusMeaning
200Success
400Bad request — invalid parameters or missing required fields
401Unauthorized — missing or invalid API key
404Resource not found
422Unprocessable entity — validation failed (e.g. slot unavailable)
500Internal server error

​
Pagination

List endpoints support limit and offset query parameters:
ParameterTypeDescription
limitintegerNumber of records to return per page
offsetintegerNumber of records to skip

​
API Sections

SectionDescription
Agent APICreate, read, update, and delete voice AI agents
Agent Tool APIManage custom tools (functions, webhooks) available to agents
Widget Settings APIConfigure embeddable chat widget appearance and behavior
Phone Number & Telephony APIBrowse, buy, import, and release phone numbers
Campaign APICreate and manage outbound voice campaigns with scheduling, concurrency, and retry logic
Contact APICreate, search, and manage contacts with call history, stats, and notes
Appointment APIBook, reschedule, cancel, and check appointment availability
Cal.com Integration APIConnect and manage Cal.com scheduling integration
RAG Knowledge Base APIIngest documents, crawl websites, and query knowledge bases
WebhooksReceive post-call data including transcripts, recordings, and AI analysis
Health APIService health and readiness checks