REST API

The Calleague REST API lets you do from code what you do in the dashboard: run your voice assistants, start and review calls, and read your account's data. This page covers the base address, Bearer authentication, the common operations, pagination, error codes, and rate limits — built around the real request and response shown in the screenshot.

Everything here is app-level: you sign in as your workspace and send requests over a secure connection. There is nothing to install.

At a glance

Base address

All requests go to your Calleague workspace, rooted at https://app.calleague.ai/api/.... Requests and responses are JSON. Set Content-Type: application/json on any request that sends a body.

Authentication

Every request carries an API key as a Bearer token in the standard Authorization header — the same Authorization: Bearer $TOKEN line you see in the screenshot:

Authorization: Bearer $TOKEN

You create, name, and revoke keys from your account settings inside the app. A key inherits your permissions, so it can do exactly what you can do — no more.

curl -s https://app.calleague.ai/api/core/voice/agent/list \
  -H "Authorization: Bearer $TOKEN"

Common operations

The first row is the real endpoint from the screenshot. The rest are the companion operations you'll reach for; treat their exact paths as illustrative and confirm them for your workspace.

Request fields — start a call

Query fields — list calls

Start a call

This is the exact request and response from the screenshot. Add an optional metadata object to carry your own reference (such as an order id).

curl -s -X POST https://app.calleague.ai/api/core/voice/agent/call \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "agentId": "ag_123",
        "to": "+90312...",
        "metadata": { "orderId": "A-1042" }
      }'

A successful start returns the new call:

{
  "callId": "cl_8f2a",
  "status": "ringing",
  "language": "tr"
}

Look up a call

Read a single call to see how it progressed — or rely on webhooks to be told instead.

curl -s https://app.calleague.ai/api/core/voice/call/cl_8f2a \
  -H "Authorization: Bearer $TOKEN"

{
  "callId": "cl_8f2a",
  "status": "completed",
  "direction": "outbound",
  "durationSec": 84,
  "endedReason": "completed",
  "language": "tr",
  "recordingReady": true,
  "transcriptReady": true,
  "createdAt": "2026-01-01T12:00:00.000Z",
  "endedAt": "2026-01-01T12:01:24.000Z"
}

Call status values

Pagination

Listing calls returns a paginated shape — always handle an empty list gracefully:

curl -s "https://app.calleague.ai/api/core/voice/call/list?page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"

{
  "total": 0,
  "list": []
}

To page through results, increase page until the number of items you've collected reaches total.

Error codes

A failed request comes back with a non-2xx status, a code, and a human-readable message. Branch on the HTTP status first.

{
  "code": 401,
  "message": "Invalid or missing API key"
}

Rate limits

The API applies fair-use limits per workspace. Build your client to cope:

If something looks different

FAQ

Next steps