Platform API

Authenticate with a business API key from your dashboard's Developers page (X-API-Key header). Keys have scopes and optional per-key spend caps. Machine-readable: /openapi.json · /llms.txt · /llms-full.txt — point your coding agent at llms.txt and it can build against us.

GET /api/v1/agents

List your agents

Every agent on your account with its status, template, assigned phone number, and client grouping (external_ref round-trips your own CRM/accounting ids).

Auth: Business API key: `X-API-Key` header or `Authorization: Bearer`. Requires the `agents` scope.

Response 200

{
    "agents": [
        {
            "agent_id": 12,
            "name": "Sophie",
            "template": "generic_reception",
            "status": "ACTIVE",
            "phone_number": "+441256222333",
            "client": {
                "client_id": 3,
                "name": "Harrison & Co",
                "external_ref": "CRM-1042"
            },
            "created_at": "2026-07-28 09:00:00"
        }
    ]
}
POST /api/v1/agents/:id/status

Pause or resume an agent

Paused agents answer with a polite unavailable message. The change applies from the next call.

Auth: Business API key with the `agents` scope.

Parameters

  • id (path, required) — Agent id

Request

{
    "status": "PAUSED"
}

Response 200

{
    "agent_id": 12,
    "status": "PAUSED"
}
GET /api/v1/clients

List your clients

The client groupings your agents roll up to for billing.

Auth: Business API key with the `agents` scope.

Response 200

{
    "clients": [
        {
            "client_id": 3,
            "name": "Harrison & Co",
            "external_ref": "CRM-1042",
            "created_at": "2026-07-01 10:00:00"
        }
    ]
}
POST /api/v1/clients

Create a client (idempotent by name)

Creates a client grouping, or returns the existing one with that name (updating external_ref if supplied) — safe to call from sync jobs.

Auth: Business API key with the `agents` scope.

Request

{
    "name": "Harrison & Co",
    "external_ref": "CRM-1042"
}

Response 200

{
    "client_id": 3,
    "name": "Harrison & Co",
    "external_ref": "CRM-1042",
    "created": true
}
GET /api/v1/calls

List calls in a date range

Filterable by agent_id and client_id; defaults to the current month. Latest 200.

Auth: Business API key with the `calls` scope.

Parameters

  • from (query) — YYYY-MM-DD (default: first of this month)
  • to (query) — YYYY-MM-DD (default: today)
  • agent_id (query) — Filter to one agent
  • client_id (query) — Filter to one client

Response 200

{
    "from": "2026-07-01",
    "to": "2026-07-28",
    "calls": [
        {
            "call_id": 88,
            "agent_id": 12,
            "channel_id": 15,
            "client_id": 3,
            "caller_number": "+447712345678",
            "started_at": "2026-07-28 14:03:11",
            "duration_seconds": 151,
            "status": "COMPLETED",
            "outcome": "message_taken",
            "summary": "Quote request",
            "charged_pence": 26
        }
    ]
}
GET /api/v1/calls/:id

One call with transcript and message

The full record: timings, outcome, the structured message taken (if any) and the conversation transcript (subject to your transcript retention window).

Auth: Business API key with the `calls` scope.

Parameters

  • id (path, required) — Call id

Response 200

{
    "call_id": 88,
    "agent_id": 12,
    "channel_id": 15,
    "client_id": 3,
    "caller_number": "+447712345678",
    "to_number": "+441256222333",
    "started_at": "2026-07-28 14:03:11",
    "ended_at": "2026-07-28 14:05:42",
    "duration_seconds": 151,
    "status": "COMPLETED",
    "outcome": "message_taken",
    "summary": "Quote request",
    "message": {
        "caller_name": "John Peters",
        "reason": "Quote request",
        "details": "Ltd company, ~40 invoices/month"
    },
    "transcript": [
        "[0:01] Agent: Hi, this is Sophie\u2026"
    ],
    "charged_pence": 26,
    "rate_ppu_used": 10
}
GET /api/v1/balance

Current credit balance

Balance in pence, billing mode, and account status.

Auth: Business API key with the `billing` scope.

Response 200

{
    "balance_pence": 892,
    "billing_mode": "CREDITS",
    "account_status": "ACTIVE"
}
GET /api/v1/ledger

Credit ledger entries in a date range

Every balance movement: grants, top-ups, usage debits (with the API key that incurred them, where applicable), adjustments. Latest 500 in range.

Auth: Business API key with the `billing` scope.

Parameters

  • from (query) — YYYY-MM-DD (default: first of this month)
  • to (query) — YYYY-MM-DD (default: today)

Response 200

{
    "from": "2026-07-01",
    "to": "2026-07-28",
    "entries": [
        {
            "entry_id": 14,
            "type": "USAGE",
            "amount_pence": -13,
            "service": "voice",
            "reference": "CA3f84\u2026",
            "balance_after_pence": 892,
            "api_key_id": null,
            "created_at": "2026-07-28 10:46:20"
        }
    ]
}
GET /api/v1/usage

Usage report: units + cost per client, agent and channel

The endpoint your billing automation calls monthly to invoice your clients: usage rolled up channel → agent → client with your external_ref on every row, filtered by date range and optionally client_id / agent_id / channel_id.

Auth: Business API key with the `billing` scope.

Parameters

  • from (query) — YYYY-MM-DD (default: first of this month)
  • to (query) — YYYY-MM-DD (default: today)
  • client_id (query) — Filter to one client
  • agent_id (query) — Filter to one agent
  • channel_id (query) — Filter to one channel

Response 200

{
    "from": "2026-07-01",
    "to": "2026-07-28",
    "usage": [
        {
            "service": "voice",
            "client_id": 3,
            "client_name": "Harrison & Co",
            "external_ref": "CRM-1042",
            "agent_id": 12,
            "agent_name": "Sophie",
            "channel_id": 15,
            "calls": 42,
            "seconds": 6510,
            "charged_pence": 1110
        }
    ]
}