API Endpoints

Agents

Virtual AI assistants that handle voice interactions.

Create Agent

POST /api/v1/agents

Create a new AI agent by selecting voice model characteristics and the underlying language model for script execution.

List Agents

GET /api/v1/agents

Retrieve a paginated list of all available agents in your account.

Get Agent

GET /api/v1/agents/{agentId}

Fetch detailed configuration and status information for a specific agent.

Update Agent

PATCH /api/v1/agents/{agentId}

Modify an existing agent's properties like name, voice settings, or personality.

Delete Agent

DELETE /api/v1/agents/{agentId}

Permanently remove an agent from your account.

Flows

Complex flows that define how agents handle calls and route conversations.

Create Flow

POST /api/v1/flows

Create a new call flow by defining flows for call handling and routing logic.

List Flows

GET /api/v1/flows

Get a paginated list of all call flows in your account.

Get Flow

GET /api/v1/flows/{flowId}

Retrieve detailed configuration for a specific call flow including routing logic.

Update Flow

PATCH /api/v1/flows/{flowId}

Modify an existing call flow and routing rules.

Delete Flow

DELETE /api/v1/flows/{flowId}

Permanently remove a call flow from your account.

Calls

Manage outbound voice calls using agents and flows.

Send Call

POST /api/v1/calls/call

Initiate a new outbound call using an AI agent.

Request Body

agentIdstringrequired

The unique identifier of the AI agent that will handle the call

toNumberstringrequired

The phone number to call in E.164 format (e.g., +1234567890)

Response

statusstring

Will be "success" if the call was initiated successfully

callIdstring

A unique identifier for the call

roomNamestring

Internal room identifier for the call session

fromNumberstring

The phone number the call will be placed from

toNumberstring

The destination phone number

agentobject

Example Response

{
  "status": "success",
  "callId": "ab12cd34ef",
  "roomName": "64f8e3b1c12d8e9a4f3c2d1e-ab12cd34ef",
  "fromNumber": "+1987654321",
  "toNumber": "+1234567890",
  "agent": {
    "id": "64f8e3b1c12d8e9a4f3c2d1e",
    "name": "Sales Assistant",
    "model": "gpt-4o-mini",
    "voice": {
      "provider": "openai",
      "voiceId": "alloy"
    }
  }
}

Error Responses

404 - Not Found

{
  "error": "Agent not found",
  "details": "The specified agent does not exist or you don't have access to it"
}

400 - Bad Request

{
  "error": "Invalid configuration",
  "details": "Agent has no phone number configured"
}

500 - Internal Server Error

{
  "error": "Failed to initiate call",
  "details": "Error message",
  "code": "UNKNOWN_ERROR"
}

Notes

The agent must have an active phone number configured
The agent must have an active flow configured
All phone numbers should be in E.164 format (+[country code][number])
Calls are recorded by default unless specified otherwise
Maximum call duration is typically 1 hour

Batch Calls

Efficiently make multiple AI-powered calls using CSV data uploads.

Download CSV Template

GET /v1/api/batch-calls/template

Download a properly formatted CSV template for batch call operations.

Validate CSV

POST /v1/api/batch-calls/validate

Validate a CSV file and preview the data before starting batch calls.

Preview CSV Data

POST /v1/api/batch-calls/preview

Preview the data from a CSV file to verify formatting and content.

Start Batch Operation

POST /v1/api/batch-calls

Initiate a batch call operation using a CSV file and specified agent.

Get Batch Status

GET /v1/api/batch-calls/{batchId}

Get detailed status information for a batch call operation.

Get Batch Progress

GET /v1/api/batch-calls/{batchId}/status

Get real-time progress information for a batch call operation.

List Batch Calls

GET /v1/api/batch-calls/{batchId}/calls

Get a paginated list of all calls within a batch operation with filtering.

Get Individual Call Status

GET /v1/api/batch-calls/{batchId}/calls/{jobId}

Get the status of an individual call within a batch operation.

Cancel Batch Operation

DELETE /v1/api/batch-calls/{batchId}

Cancel a batch call operation and stop remaining calls from processing.