REST API

Call the Calleague app API with a Bearer token — start and list calls, read assistants, and handle JSON responses.

The Calleague REST API lets you do from code what you do in the dashboard: manage voice assistants, start and review calls, and read your account's data. This page covers the base URL, Bearer authentication, and an illustrative curl request and response you can adapt.

Base URL

All requests go to your Calleague workspace API. Set it once and reuse it:

# Illustrative base URL — use your own workspace
export CALLEAGUE_BASE="https://app.calleague.ai"

Authentication

Every request carries an API key as a Bearer token in the standard Authorization header:

Authorization: Bearer <YOUR_API_KEY>

You create, name, and revoke keys from your account settings inside the app. A key inherits your permissions, so scope it to what the integration needs and rotate it if it leaks.

🔒

Never hardcode a key into scripts, repositories, or documentation. Keep it in your own secret store and inject it at runtime. The keys shown here are placeholders, not real credentials.

A request, end to end

The illustration below shows the shape of a typical authenticated request and its JSON response.

API request and response

curl example

The example below is illustrative — the path, body, and field names are generic placeholders that show the request shape, not a guaranteed live route. Adapt them to the resource you are working with.

# Illustrative only — generic placeholders, not a guaranteed live route
curl -s -X POST "$CALLEAGUE_BASE/api/v1/calls" \
  -H "Authorization: Bearer $CALLEAGUE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "assistantId": "<your-assistant-id>",
        "to": "+1XXXXXXXXXX"
      }'

A successful response is JSON. A common shape wraps the result in a code / data envelope:

{
  "code": 200,
  "statusText": "",
  "data": {
    "callId": "<call-id>",
    "status": "queued",
    "createdAt": "2026-01-01T12:00:00.000Z"
  }
}

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

curl -s "$CALLEAGUE_BASE/api/v1/calls?page=1&pageSize=20" \
  -H "Authorization: Bearer $CALLEAGUE_API_KEY"

{
  "code": 200,
  "data": {
    "total": 0,
    "list": []
  }
}

💡

When consuming any response in your own code, apply defensive checks (optional chaining / null-coalescing) before calling array methods like .map(). A list endpoint can legitimately return an empty list, and assuming a populated shape is the most common integration bug.

Errors

Authentication failures return an error envelope — re-check that the Authorization: Bearer header is present and the key is still valid.
Always set Content-Type: application/json on requests that send a JSON body.
List endpoints return an empty list rather than failing when there is nothing to return — handle that case.

Webhooks & events — receive call-lifecycle events in real time.
MCP — connect Calleague to Model Context Protocol clients.