Calls Endpoints

Endpoints for initiating voice calls and monitoring their status and transcripts.

Initiate Call

POST /api/v1/calls

Start a new voice call using a workflow.

Request Body:

{
  "workflow_slug": "daily-call",
  "user_id": "user-123",
  "user_data": {
    "name": "John Doe",
    "language": "en"
  },
  "metadata": {
    "session_id": "abc123",
    "source": "mobile-app"
  }
}

Required Fields:

Field	Type	Description
`workflow_slug`	string	Workflow to use for this call

Optional Fields:

Field	Type	Description
`user_id`	string	External user identifier
`user_data`	object	User data available as `{{user.*}}` in templates
`metadata`	object	Additional metadata stored with call

Response:

{
  "call_id": "uuid",
  "room_name": "call-uuid",
  "livekit_url": "wss://livekit.example.com",
  "token": "eyJ...",
  "status": "connecting"
}

Field	Description
`call_id`	Unique call identifier
`room_name`	LiveKit room name for connection
`livekit_url`	LiveKit server WebSocket URL
`token`	JWT token for LiveKit authentication
`status`	Initial call status

Get Call

GET /api/v1/calls/{id}

Get call status and details.

Path Parameters:

Parameter	Type	Description
`id`	uuid	Call ID

Response:

{
  "id": "uuid",
  "workflow_id": "uuid",
  "workflow_slug": "daily-call",
  "user_id": "user-123",
  "status": "completed",
  "direction": "outbound",
  "duration_seconds": 180,
  "agent_history": ["greeter-agent", "meal-agent", "feedback-agent"],
  "current_agent": null,
  "metrics": {
    "duration_seconds": 180,
    "stt_latency_ms": 120,
    "llm_latency_ms": 280,
    "tts_latency_ms": 85,
    "total_tokens": 1500,
    "agent_handoffs": 2
  },
  "started_at": "2026-01-17T10:30:00Z",
  "ended_at": "2026-01-17T10:33:00Z",
  "created_at": "2026-01-17T10:29:55Z"
}

Get Call Transcript

GET /api/v1/calls/{id}/transcript

Get the full transcript of a call.

Path Parameters:

Parameter	Type	Description
`id`	uuid	Call ID

Response:

[
  {
    "role": "system",
    "content": "Call started",
    "timestamp": "2026-01-17T10:30:00Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "assistant",
    "content": "Hello! How are you today?",
    "timestamp": "2026-01-17T10:30:05Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "user",
    "content": "I'm doing well, thanks!",
    "timestamp": "2026-01-17T10:30:10Z",
    "agent_name": "greeter-agent"
  },
  {
    "role": "assistant",
    "content": "Great! What did you have for breakfast?",
    "timestamp": "2026-01-17T10:30:15Z",
    "agent_name": "meal-agent",
    "tool_call": {
      "name": "save_meal",
      "arguments": { "meal_type": "breakfast" }
    }
  }
]

Get Call Metrics

GET /api/v1/calls/{id}/metrics

Get performance metrics for a call.

Response:

{
  "duration_seconds": 180,
  "stt_latency_ms": 120,
  "llm_latency_ms": 280,
  "tts_latency_ms": 85,
  "total_tokens": 1500,
  "agent_handoffs": 2
}

List Calls

GET /api/v1/calls

List calls with filtering and pagination.

Query Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`page_size`	integer	Items per page (default: 20, max: 100)
`status`	string	Filter by status
`workflow_id`	uuid	Filter by workflow
`user_id`	string	Filter by user
`started_after`	datetime	Filter by start time (after)
`started_before`	datetime	Filter by start time (before)

Response:

{
  "items": [
    {
      "id": "uuid",
      "workflow_id": "uuid",
      "workflow_slug": "daily-call",
      "user_id": "user-123",
      "status": "completed",
      "duration_seconds": 180,
      "agent_history": ["greeter-agent", "meal-agent"],
      "started_at": "2026-01-17T10:30:00Z",
      "ended_at": "2026-01-17T10:33:00Z"
    }
  ],
  "total": 100,
  "page": 1,
  "page_size": 20,
  "pages": 5
}

List Active Calls

GET /api/v1/calls/active

List currently active calls.

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50, max: 100)

Response:

[
  {
    "id": "uuid",
    "workflow_slug": "daily-call",
    "user_id": "user-456",
    "status": "active",
    "current_agent": "meal-agent",
    "started_at": "2026-01-17T10:35:00Z"
  }
]

Call Status Values

Status	Description
`pending`	Call initiated, waiting for connection
`connecting`	Establishing connection
`active`	Call in progress
`completed`	Call ended normally
`failed`	Call failed to connect
`disconnected`	Call dropped unexpectedly
`timeout`	Call timed out

Call Direction

Direction	Description
`inbound`	User initiated the call
`outbound`	System initiated the call

Provider Keys Endpoints

List Provider Keys

GET /api/v1/provider-keys

List configured BYOK provider keys (key values are masked).

Response:

{
  "items": [
    {
      "id": "uuid",
      "provider_type": "stt",
      "provider_name": "deepgram",
      "is_default": true,
      "created_at": "2026-01-17T10:30:00Z"
    }
  ]
}

Create Provider Key

POST /api/v1/provider-keys

Add a BYOK provider key.

Request Body:

{
  "provider_type": "stt",
  "provider_name": "deepgram",
  "api_key": "dg_xxxxx",
  "is_default": true
}

Delete Provider Key

DELETE /api/v1/provider-keys/{id}

Delete a provider key. Returns 204 on success.

Calls Endpoints

On this page