# BytePilot

> White-label AI services platform for agencies and resellers. Credit-based
> billing (GBP pence), named API keys with scopes and per-key spend caps.

Base URL: https://bytepilot.ai
Auth: X-API-Key header (or Authorization: Bearer) with a business API key
from your dashboard Developers page. Keys have scopes (agents, calls,
billing) and optional per-key daily/monthly spend caps (HTTP 402 when hit).

## Docs
- Full endpoint reference: https://bytepilot.ai/llms-full.txt
- OpenAPI spec: https://bytepilot.ai/openapi.json
- Human docs: https://bytepilot.ai/developers

## Endpoints
- GET /api/v1/agents — List your agents
- POST /api/v1/agents/:id/status — Pause or resume an agent
- GET /api/v1/clients — List your clients
- POST /api/v1/clients — Create a client (idempotent by name)
- GET /api/v1/calls — List calls in a date range
- GET /api/v1/calls/:id — One call with transcript and message
- GET /api/v1/balance — Current credit balance
- GET /api/v1/ledger — Credit ledger entries in a date range
- GET /api/v1/usage — Usage report: units + cost per client, agent and channel

---

## 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 example (200):
```json
{
    "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"
        }
    ]
}
```

Status codes: 200 = Agent list; 401 = Invalid key; 403 = Missing scope; 402 = Key spend cap reached

---

## 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, integer, required): Agent id

Request example:
```json
{
    "status": "PAUSED"
}
```

Response example (200):
```json
{
    "agent_id": 12,
    "status": "PAUSED"
}
```

Status codes: 200 = Updated; 400 = Bad status; 404 = Unknown agent; 401 = Invalid key; 403 = Missing scope

---

## 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 example (200):
```json
{
    "clients": [
        {
            "client_id": 3,
            "name": "Harrison & Co",
            "external_ref": "CRM-1042",
            "created_at": "2026-07-01 10:00:00"
        }
    ]
}
```

Status codes: 200 = Client list; 401 = Invalid key; 403 = Missing scope

---

## 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 example:
```json
{
    "name": "Harrison & Co",
    "external_ref": "CRM-1042"
}
```

Response example (200):
```json
{
    "client_id": 3,
    "name": "Harrison & Co",
    "external_ref": "CRM-1042",
    "created": true
}
```

Status codes: 200 = Created or matched; 400 = Missing name; 401 = Invalid key; 403 = Missing scope

---

## 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, string): YYYY-MM-DD (default: first of this month)
- to (query, string): YYYY-MM-DD (default: today)
- agent_id (query, integer): Filter to one agent
- client_id (query, integer): Filter to one client

Response example (200):
```json
{
    "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
        }
    ]
}
```

Status codes: 200 = Call list; 401 = Invalid key; 403 = Missing scope

---

## 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, integer, required): Call id

Response example (200):
```json
{
    "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
}
```

Status codes: 200 = Call detail; 404 = Unknown call; 401 = Invalid key; 403 = Missing scope

---

## GET /api/v1/balance

Current credit balance. Balance in pence, billing mode, and account status.

Auth: Business API key with the billing scope.

Response example (200):
```json
{
    "balance_pence": 892,
    "billing_mode": "CREDITS",
    "account_status": "ACTIVE"
}
```

Status codes: 200 = Balance; 401 = Invalid key; 403 = Missing scope

---

## 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, string): YYYY-MM-DD (default: first of this month)
- to (query, string): YYYY-MM-DD (default: today)

Response example (200):
```json
{
    "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"
        }
    ]
}
```

Status codes: 200 = Ledger entries; 401 = Invalid key; 403 = Missing scope

---

## 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, string): YYYY-MM-DD (default: first of this month)
- to (query, string): YYYY-MM-DD (default: today)
- client_id (query, integer): Filter to one client
- agent_id (query, integer): Filter to one agent
- channel_id (query, integer): Filter to one channel

Response example (200):
```json
{
    "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
        }
    ]
}
```

Status codes: 200 = Usage rows; 401 = Invalid key; 403 = Missing scope

---