{ "openapi": "3.1.0", "info": { "title": "BytePilot Platform API", "description": "The BytePilot business API. Authenticate with an API key from your dashboard Developers page (X-API-Key header). Keys have scopes (agents, calls, billing) and optional per-key spend caps.", "version": "0.2.0", "contact": { "email": "support@bytepilot.ai" } }, "servers": [ { "url": "https://bytepilot.ai" } ], "components": { "securitySchemes": { "apiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Business API key from your dashboard Developers page" } } }, "paths": { "/api/v1/agents": { "get": { "summary": "List your agents", "description": "Every agent on your account with its status, template, assigned phone number, and client grouping (external_ref round-trips your own CRM/accounting ids).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Agent list", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" }, "402": { "description": "Key spend cap reached" } } } }, "/api/v1/agents/:id/status": { "post": { "summary": "Pause or resume an agent", "description": "Paused agents answer with a polite unavailable message. The change applies from the next call.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Updated", "content": { "application/json": { "example": { "agent_id": 12, "status": "PAUSED" } } } }, "400": { "description": "Bad status" }, "404": { "description": "Unknown agent" }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Agent id", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "example": { "status": "PAUSED" } } } } } }, "/api/v1/clients": { "get": { "summary": "List your clients", "description": "The client groupings your agents roll up to for billing.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Client list", "content": { "application/json": { "example": { "clients": [ { "client_id": 3, "name": "Harrison & Co", "external_ref": "CRM-1042", "created_at": "2026-07-01 10:00:00" } ] } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } } }, "post": { "summary": "Create a client (idempotent by name)", "description": "Creates a client grouping, or returns the existing one with that name (updating external_ref if supplied) \u2014 safe to call from sync jobs.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Created or matched", "content": { "application/json": { "example": { "client_id": 3, "name": "Harrison & Co", "external_ref": "CRM-1042", "created": true } } } }, "400": { "description": "Missing name" }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "requestBody": { "required": true, "content": { "application/json": { "example": { "name": "Harrison & Co", "external_ref": "CRM-1042" } } } } } }, "/api/v1/calls": { "get": { "summary": "List calls in a date range", "description": "Filterable by agent_id and client_id; defaults to the current month. Latest 200.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Call list", "content": { "application/json": { "example": { "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 } ] } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD (default: first of this month)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD (default: today)", "schema": { "type": "string" } }, { "name": "agent_id", "in": "query", "required": false, "description": "Filter to one agent", "schema": { "type": "integer" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter to one client", "schema": { "type": "integer" } } ] } }, "/api/v1/calls/:id": { "get": { "summary": "One call with transcript and message", "description": "The full record: timings, outcome, the structured message taken (if any) and the conversation transcript (subject to your transcript retention window).", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Call detail", "content": { "application/json": { "example": { "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 } } } }, "404": { "description": "Unknown call" }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Call id", "schema": { "type": "integer" } } ] } }, "/api/v1/balance": { "get": { "summary": "Current credit balance", "description": "Balance in pence, billing mode, and account status.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Balance", "content": { "application/json": { "example": { "balance_pence": 892, "billing_mode": "CREDITS", "account_status": "ACTIVE" } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } } } }, "/api/v1/ledger": { "get": { "summary": "Credit ledger entries in a date range", "description": "Every balance movement: grants, top-ups, usage debits (with the API key that incurred them, where applicable), adjustments. Latest 500 in range.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Ledger entries", "content": { "application/json": { "example": { "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" } ] } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD (default: first of this month)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD (default: today)", "schema": { "type": "string" } } ] } }, "/api/v1/usage": { "get": { "summary": "Usage report: units + cost per client, agent and channel", "description": "The endpoint your billing automation calls monthly to invoice your clients: usage rolled up channel \u2192 agent \u2192 client with your external_ref on every row, filtered by date range and optionally client_id / agent_id / channel_id.", "security": [ { "apiKey": [] } ], "responses": { "200": { "description": "Usage rows", "content": { "application/json": { "example": { "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 } ] } } } }, "401": { "description": "Invalid key" }, "403": { "description": "Missing scope" } }, "parameters": [ { "name": "from", "in": "query", "required": false, "description": "YYYY-MM-DD (default: first of this month)", "schema": { "type": "string" } }, { "name": "to", "in": "query", "required": false, "description": "YYYY-MM-DD (default: today)", "schema": { "type": "string" } }, { "name": "client_id", "in": "query", "required": false, "description": "Filter to one client", "schema": { "type": "integer" } }, { "name": "agent_id", "in": "query", "required": false, "description": "Filter to one agent", "schema": { "type": "integer" } }, { "name": "channel_id", "in": "query", "required": false, "description": "Filter to one channel", "schema": { "type": "integer" } } ] } } } }