API Reference

All endpoints are served by the Next.js app. Desktop and mobile clients communicate exclusively through these routes — no direct Supabase access.

Base URLhttp://<your-server>:3000

Calls

Manage call records stored in the database.

GET/api/calls— List all calls

Returns a paginated list of call records. Supports optional query params: ?limit, ?status (answered | missed | rejected), ?agent_id.

Param	In	Description
limit	query	Max records to return (default 50)
status	query	Filter by call status
agent_id	query	Filter by agent

POST/api/calls— Insert a new call

Creates a new call record. Called by the desktop app when a call event is received from the mobile gateway.

Param	In	Description
caller_number	body	Incoming phone number
gateway_id	body	ID of the originating gateway
agent_id	body	Agent that handled the call
status	body	Initial call status

GET/api/calls/stats— Dashboard statistics

Returns aggregated call stats: total calls, answered/missed/rejected counts, and average call duration. Used by the dashboard page.

GET/api/calls/[id]— Get a single call

Fetches the full record for one call by its UUID.

Param	In	Description
id	path	Call UUID

PATCH/api/calls/[id]— Update a call

Updates mutable fields on a call — typically status, answered_at, ended_at, or duration. Called by the desktop app during and after a call.

Param	In	Description
id	path	Call UUID
status	body	New status value
answered_at	body	ISO timestamp when answered
ended_at	body	ISO timestamp when ended
duration	body	Duration in seconds

Agents

Manage the agents (operators) who answer calls via the desktop app.

GET/api/agents— List all agents

Returns all agents with their linked gateway info and call statistics (total, answered, missed).

POST/api/agents— Create an agent

Creates a new agent record. A random pairing_secret is generated automatically for QR-based gateway registration.

Param	In	Description
name	body	Agent display name
email	body	Agent email (used for sign-in)

GET/api/agents/[id]— Agent detail

Returns a single agent with full stats and the 10 most recent calls.

Param	In	Description
id	path	Agent UUID

PATCH/api/agents/[id]— Update an agent

Updates agent fields: name, email, or status (active | inactive).

Param	In	Description
id	path	Agent UUID
name	body	New display name
email	body	New email address
status	body	active \| inactive

GET/api/agents/[id]/pairing-secret— Get pairing data for QR

Returns the pairing_secret for the given agent. The desktop QR screen calls this to build the QR payload that the mobile app scans.

Param	In	Description
id	path	Agent UUID

POST/api/agents/signin— Agent sign-in

Looks up an agent by email. Returns the agent record on match. No password required — email-only authentication for the desktop app.

Param	In	Description
email	body	Agent email address

Gateways

Manage mobile phone gateways (Android phones that forward SIM calls).

POST/api/gateways/register— Register a gateway

Called by the mobile app after scanning the QR code. Verifies the pairing_secret, then upserts a gateway record tied to the agent. Returns a gateway_token the mobile app stores for subsequent requests. Re-scanning the QR after reinstall works cleanly (upsert by phone_number).

Param	In	Description
agent_id	body	Agent to pair with
pairing_secret	body	Secret from QR payload
phone_number	body	SIM phone number auto-detected on device

GET/api/gateways/[id]— Get a gateway

Returns the gateway record (status, phone_number, last_seen, linked agent).

Param	In	Description
id	path	Gateway UUID

PATCH/api/gateways/[id]— Update a gateway

Updates gateway fields such as ws_url (WebSocket address) or status (online | offline). Called by the desktop app when its IP or port changes.

Param	In	Description
id	path	Gateway UUID
ws_url	body	New WebSocket URL
status	body	online \| offline