← Back to Documentation

API Reference

VoiceRail has two services: the API for management and the Voice service for calls.

Base URLs

APIhttps://api.voicerail.ai/v1
Voicehttps://voice.voicerail.ai/api/v1

Authentication

All API requests require two headers:

Authentication
# All requests require these headers
curl https://api.voicerail.ai/v1/assistants \
  -H "Authorization: Bearer $VOICERAIL_KEY" \
  -H "X-Organization-Id: org_xxxx"
  • Authorization - Bearer token from dashboard
  • X-Organization-Id - Your organization ID

API Endpoints

Management endpoints for assistants, organizations, phone numbers, and archetypes.

Assistants

MethodEndpointDescription
POST/assistantsCreate a new assistant
GET/assistantsList all assistants
GET/assistants/:idGet assistant by ID
PUT/assistants/:idUpdate assistant
DELETE/assistants/:idDelete assistant
Create Assistant
curl -X POST https://api.voicerail.ai/v1/assistants \
  -H "Authorization: Bearer $VOICERAIL_KEY" \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alex",
    "archetype": "helper",
    "discProfile": {
      "dominance": 45,
      "influence": 70,
      "steadiness": 60,
      "conscientiousness": 50
    },
    "voice": {
      "provider": "azure",
      "voiceId": "en-US-JennyNeural"
    }
  }'

Organizations

MethodEndpointDescription
POST/organizationsCreate organization
GET/organizations/:idGet organization by ID
PUT/organizations/:idUpdate organization (MCP servers, hold music)
DELETE/organizations/:idDelete organization

Phone Numbers

MethodEndpointDescription
POST/phone-numbersCreate phone number mapping
GET/phone-numbersList all phone number mappings
GET/phone-numbers/:idGet phone number mapping by ID
GET/phone-numbers/by-number/:numberLookup by E.164 phone number
PUT/phone-numbers/:idUpdate phone number mapping
DELETE/phone-numbers/:idDelete phone number mapping

Custom Archetypes

MethodEndpointDescription
POST/archetypesUpload custom archetype (YAML)
GET/archetypesList custom archetypes
GET/archetypes/:nameGet archetype by name
DELETE/archetypes/:nameDelete custom archetype

Call Sessions (Real-time)

MethodEndpointDescription
GET/call-sessionsList active call sessions
GET/call-sessions/:idGet active session details

Call sessions show active (non-terminal) calls. Poll every 2-5 seconds for monitoring.

Health & Info

MethodEndpointDescription
GET/healthHealth check endpoint
GET/Service info (version, environment)

Voice Service Endpoints

Call management endpoints on the Voice service (voice.voicerail.ai).

Calls

MethodEndpointDescription
POST/callsInitiate outbound call
GET/callsList calls (filter by assistant, status, date)
GET/calls/:idGet call details
GET/calls/:id/transcriptGet call transcript (JSON or text)
GET/calls/:id/recordingGet recording download URL (24h expiry)
GET/calls/:id/live-transcriptGet live transcript (active calls only)
GET/calls/:id/live-stateGet live state with memory (active calls)
Initiate Call
# Note: Calls are made to the Voice service, not the API
# fromPhoneNumber is optional - defaults to assistant's mapped number
curl -X POST https://voice.voicerail.ai/api/v1/calls \
  -H "Authorization: Bearer $VOICERAIL_KEY" \
  -H "X-Organization-Id: $ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "assistantId": "asst_xxx",
    "toPhoneNumber": "+15551234567"
  }'

Error Handling

All errors return JSON with a consistent structure:

Error Response
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The assistant_id field is required",
  "errors": {
    "assistantId": ["The AssistantId field is required."]
  }
}
StatusMeaning
400Bad request - invalid parameters or validation failed
401Unauthorized - invalid or missing API key
403Forbidden - valid key but no permission for resource
404Not found - resource doesn't exist
409Conflict - resource already exists or concurrent modification
429Rate limited - too many requests
503Service unavailable - database or ACS error
500Server error - unexpected error occurred

Rate Limits

Default rate limits by plan:

PlanRequests/minConcurrent Calls
Free602
Pro60020
EnterpriseCustomCustom

Rate limit headers are included in every response:

  • X-RateLimit-Limit - Requests allowed per window
  • X-RateLimit-Remaining - Requests remaining
  • X-RateLimit-Reset - Unix timestamp when window resets

OpenAPI Specification

The full OpenAPI (Swagger) specification is available at:

  • Swagger UI: https://api.voicerail.ai/docs
  • OpenAPI JSON: https://api.voicerail.ai/swagger/v1/swagger.json

Use these to generate client libraries for your language of choice.

Next steps