Control-Plane API

These are the endpoints the SIP edge, the media engine, agent apps, and operator tools call. They are gated (see Authentication) and not a public surface. Bodies are form-encoded or JSON; responses are JSON.

Note

This reference reflects the live control plane. The public CRUD API for the resource model is the separate, roadmap /v1 surface.

SIP-facing

POST /auth

REGISTER/INVITE digest authentication. the SIP signaling layer posts the parsed digest params; the edge runtime verifies against sip_device.ha1 and returns the account context. See Authentication.

POST /route

The routing brain. Resolves a call’s direction and returns routing JSON (rtjson) telling the SIP signaling layer what to do.

• Inbound (To = one of our DIDs) → the DID’s route target (often a flow), after CAC and business-hours overrides.
• Internal (authed device → an extension) → proxy to the target’s registered AOR.
• Outbound (authed device → PSTN) → CAC, then a customer trunk or the wholesale default.

// request (form or JSON)
{ "callId": "abc123", "from": "1001", "fromDomain": "acme.sip.io", "to": "12025550123" }

// response: run a flow
{ "rtjson": { "action": "flow", "account_id": "acc_01jf18ah3jeb5w6dfp27sgjsbt", "flow_id": "flow_01jzqwjn803wtnhc445bvjenzc", "vars": { "caller_cid": "14155551234" } } }

Other actions: proxy (to an AOR), outbound (to a trunk/carrier), reject (with a SIP code).

POST /flow

The call-flow command loop (poll-based). Start a flow, or step it with an outcome.

// start
{ "callId": "abc123", "accountId": "acc_01jf18ah3jeb5w6dfp27sgjsbt", "flowId": "flow_01jzqwjn803wtnhc445bvjenzc" }
// step
{ "callId": "abc123", "outcome": "digit:1", "data": { } }

The response is the next command for the edge to execute (play, gather, dial, enqueue, record, conference, hangup, noop). Internally this advances the per-call CallSessionDO.

POST /presence/event

SIP lifecycle events from the SIP signaling layer → the per-account PresenceDO. type is register, dialog, or agent. Drives presence, reachability, CAC release, and the CDR/trace.

Agents & ACD

Method & path	Purpose
POST /agent	Agent control: login / logout / available / pause / unpause + queue membership. Body: { accountId, userId, event, queues? }.
GET /agent?accountId=&userId=	Read one agent’s live presence (status / state / reachable / queues).
GET /presence/users?accountId=	Account-wide presence roster + status-count tiles (for dashboards).
GET /agent/confirm/{accountId}/{leaseId}/{epoch}	the media engine answer hook → confirm the queue lease.
GET /agent/claim/{accountId}/{agentId}/{callId}	the media engine answer hook (ring_all) → first answerer claims the caller.

See Agents & Presence.

Concurrency (CAC)

Method & path	Purpose
GET /cac?accountId=	Live channel-usage view: concurrency counters + active calls.
POST /cac/reset	Ops: clear stuck/leaked counters. Body: { accountId }.

See Concurrency Control.

Support & observability

Method & path	Purpose
GET /calls/{callId}/trace	The full ordered execution trace for one call (steps, commands, outcomes, errors).
GET /debug	Live dev monitor (WebSocket, session object-terminated). Gated by localhost / IP-allowlist / admin token.

See Observability.

Security

Method & path	Purpose
POST /security/report	Node → current ban snapshot (reported ~every 30s).
GET /security/bans	List / search bans (filters: status, q, flagged, limit).
GET /security/allow	List the allowlist (ACL).
POST /security/allow	Add to the allowlist / unban.
DELETE /security/allow/{ip}	Remove from the allowlist.

See The Media Edge → Security.

Media

Method & path	Purpose
GET /media/{key}	Serve playback media (prompts/greetings/MOH) from the private object storage bucket. media-node-IP gated.
PUT /media/{key}	the media engine uploads a finished voicemail recording → private object storage. media-node-IP gated.

Admin

Method & path	Purpose
POST /admin/tts/generate	Synthesize the system-prompt catalog into object storage. Gated by x-admin-token. Query: ?lang=, ?gender=, ?force=1. See Media & TTS.

Roadmap (stubbed)

Method & path	Status
/v1/*	501 (the public REST API). See Public API (v1).
/hooks/carrier	501 (inbound wholesale-carrier webhooks).