Skip to main content

​
Authentication

All endpoints (except public auth routes) require one of:
  • JWT cookie: access_token cookie (HS256, issued by /auth/login)
  • API key: X-API-Key header (workspace-scoped)
Role abbreviations: M = member, D = developer, A = admin, S = superuser

​
Auth Module — /auth

MethodPathAuthDescription
POST/auth/loginNoneLogin with email/password → JWT tokens
POST/auth/signupNoneRegister new user
POST/auth/refreshRefresh cookieRefresh access token
POST/auth/logoutJWTClear auth cookies
POST/auth/googleNoneGoogle OAuth login
POST/auth/forgot-passwordNoneSend password reset email
POST/auth/reset-passwordNoneReset password with token

​
Agents Module — /agents

​
POST /agents — Create Agent

Auth: D, A 
{
  "phone_number": "+16505551234",
  "LLM_provider": "open ai",
  "LLM_model": "gpt-4o",
  "STT_provider": "deepgram",
  "TTS_provider": "openai",
  "agent_name": "Sales Agent",
  "system_prompt": "You are a helpful sales assistant...",
  "first_message": "Hello! How can I help you today?",
  "temperature": 0.7,
  "max_tokens": 1024,
  "max_call_duration": 300,
  "custom_functions": [
    {
      "name": "check_inventory",
      "description": "Check product availability",
      "url": "https://api.example.com/inventory",
      "method": "POST",
      "parameters": {}
    }
  ]
}

​
All Agent Endpoints

MethodPathAuthDescription
GET/agentsM, D, AList agents (workspace-scoped)
POST/agentsD, ACreate agent
GET/agents/{id}M, D, AGet agent by ID
PUT/agents/{id}D, AUpdate agent
DELETE/agents/{id}D, ADelete agent
POST/agents/{id}/uploadD, AUpload knowledge base files
GET/agents/{id}/filesM, D, AList uploaded files
DELETE/agents/{id}/files/{filename}D, ADelete a file
POST/agents/{id}/queryM, D, AQuery knowledge base (RAG)

​
Calls Module — /calls

​
GET /calls — List Call Logs (Paginated)

Auth: M, D, A
ParamTypeDescription
pageintPage number (default: 1)
page_sizeintItems per page (default: 25, max: 100)
call_typestring"web" or "phone"
call_directionstring"inbound" or "outbound"
agent_idstringFilter by agent
dispositionstringCall disposition filter
start_datetimestringStart of date range
end_datetimestringEnd of date range
batch_idUUIDFilter by batch job
Response: 
{
  "items": [],
  "total": 150,
  "page": 1,
  "page_size": 25,
  "has_next": true,
  "has_prev": false
}

​
POST /calls/outbound_call — Initiate Outbound Call

Auth: JWT 
{
  "agent_phone_number": "+16505551234",
  "phone_number_to_dial": "+14155559876",
  "dynamic_variables": {
    "customer_name": "John",
    "appointment_date": "2026-02-15"
  }
}

​
All Call Endpoints

MethodPathAuthDescription
GET/calls/generate-tokenNoneGenerate LiveKit access token
GET/callsM, D, AList call logs (paginated, filtered)
GET/calls/exportM, D, AExport call logs as CSV
GET/calls/{id}M, D, AGet single call log
POST/calls/outbound_callJWTInitiate outbound call

​
Phone Numbers Module — /phonenumbers

​
POST /phonenumbers/sip_trunk — Register SIP Trunk

{
  "sip_address": "sip.example.com",
  "phone_number": "+16505551234",
  "email": "[email protected]",
  "provider": "vonage",
  "auth_username": "user",
  "auth_password": "pass",
  "krisp_enabled": true,
  "label": "Main Line"
}

​
All Phone Number Endpoints

MethodPathAuthDescription
GET/phonenumbersM, D, AList phone numbers
GET/phonenumbers/searchNoneSearch available numbers
POST/phonenumbers/purchaseD, APurchase & provision
POST/phonenumbers/sip_trunkD, ARegister SIP trunk
PUT/phonenumbers/map_agentM, D, AMap agent to number
PUT/phonenumbers/update_sip/{number}D, AUpdate SIP config
DELETE/phonenumbers/delete_sip/{number}D, ADelete SIP

​
Batch Module — /batch

MethodPathAuthDescription
GET/batchM, D, AList batch jobs
POST/batch/uploadM, D, AUpload CSV + create batch
GET/batch/{id}M, D, AGet batch status + progress
PATCH/batch/{id}M, D, AUpdate batch schedule
DELETE/batch/{id}M, D, ADelete batch

​
Campaigns Module (Vaani Dialer) — /api/v/

Coming Soon — The Campaign Scheduler API is in development and available on the Dev instance for testing.
The Vaani Dialer exposes a Django REST API at /api/v/ with campaign CRUD, prospect list uploads, and status endpoints.
MethodPathAuthDescription
GET/api/v/campaign/JWTList campaigns (filter by email, workspace)
POST/api/v/campaign/JWTCreate campaign
GET/api/v/campaign/{slug}/JWTGet campaign details
PUT/PATCH/api/v/campaign/{slug}/JWTUpdate campaign (clears cache)
DELETE/api/v/campaign/{slug}/JWTDelete campaign (clears cache)
GET/api/v/campaign/{slug}/status/NoneReal-time campaign status
POST/api/v/upload/{slug}/JWTUpload prospect list CSV
POST/api/v/upload/{uuid}/retry/JWTRetry failed upload
POST/api/v/prospect/{uuid}/JWTAdd single prospect
GET/api/v/options/JWTCampaign configuration options
GET/api/v/live/JWTLive call activity
DELETE/api/v/delete-cache/JWTClear campaign cache
POST/api/v/webhook/NoneDialer webhook events

​
Workspaces Module — /workspaces

MethodPathAuthDescription
POST/workspacesJWTCreate workspace
GET/workspacesJWTList workspaces (superuser: all)
GET/workspaces/{id}M, D, AGet workspace
PATCH/workspaces/{id}AUpdate workspace
DELETE/workspaces/{id}ADelete workspace
POST/workspaces/switchJWTSwitch active workspace
GET/workspaces/{id}/membersM, D, AList members
POST/workspaces/{id}/inviteAInvite member
DELETE/workspaces/{id}/members/{uid}ARemove member

​
Reports Module — /reports

MethodPathAuthDescription
GET/reports/dashboardM, D, ADashboard data
GET/reports/call-summaryM, D, ACall summary
GET/reports/disposition-summaryM, D, ADisposition summary
GET/reports/workloadNoneAgent workload (Prometheus)

​
Chats Module — /chats

MethodPathAuthDescription
POST/chatsM, D, AChat interaction
GET/chatsM, D, AList chat logs

​
Webhooks Module — /webhook

MethodPathAuthDescription
POST/webhook/livekitNoneLiveKit webhook events
Behavior:
  • room_started → increment Redis livekit:active_calls
  • room_finished → decrement Redis livekit:active_calls

​
Common Error Codes

CodeMeaning
400Validation error / bad request
401Not authenticated / token expired
403Insufficient role / not a workspace member
404Resource not found
409Conflict (e.g., duplicate slug)
500Internal server error