API reference
One contract, the whole platform
The SOMVAD API is a published, versioned contract for external integrators. It is an OpenAPI 3.1 document spanning 138 endpoints across 30 domains, regenerated from the running application on every change. Request and response types never drift from the server.
The explorer, spec, and guide on the live deployment are access-gated. Request credentials and we'll point you at them.
Domain map
The surface, grouped by what you build
Every tag in the spec, in plain terms. Open any of these in the Swagger explorer for request and response shapes.
Identity & access
auth
Login, token introspection (/auth/me), OIDC config, and platform-admin impersonation.
tenants
Organisations and their policy: onboarding with a first admin, record/retention policy, CSV/JSON export & import.
users
Per-tenant profiles: create with a password, clone a template trader, assign across tenants, set role.
desks
Trading desks, desk heads, and seating: the supervision scope for barge.
entitlements
Which users may see and join which resources.
audit
Immutable audit events; impersonation and mutating actions are recorded.
Voice & conferences
conferences
The core primitive: create, join (mixer placement), leave, lock/unlock, barge, members, topology, events.
calls
Ring a user, accept / decline / cancel, invite and blind-transfer into a live call.
lines
DDI line appearances and shared-line state (busy-lamp).
hoots
Always-on hoot and squawk rooms.
private-wires
Point-to-point ring-down wires.
browser
Per-call SIP credential + ICE/TURN config for WebRTC, and audio test-dial numbers.
sip
SIP credentials and registrations: the runtime location service.
layouts
The turret button matrix: the trader's grid, pages, and handset count.
profiles
Reusable sound-card profiles (output + input) and per-target assignments.
Realtime
presence
Online / available / in-conference / speaking state, plus the events WebSocket.
chat
Messages on any conference: call chat, group rooms, and DMs, one model.
stt
Live captions and transcription controls.
Compliance & operations
recordings
Mixer and edge-signed recordings, transcripts, retention, playback, and tamper verification.
gateways
Carrier trunks and DID routing for inbound and outbound PSTN.
metering
Usage accounting per tenant.
metrics
Voice QoS (MOS / jitter / loss) and API latency; a Prometheus exposition.
mixers
The media worker pool: registry, scaling, drain status.
system
Live architecture topology and SIP logs for operators.
bugs
In-platform field bug reports with trace correlation.
share
Public share links for reports.
Authentication
Send a bearer token on every request except the few public ones (/health, /auth/login, /auth/config). The token's tenant_id selects which per-tenant profile you act as. OIDC tokens (Microsoft Entra) are accepted on the same endpoints when configured.
header
Authorization: Bearer <your-token>
Error contract
Errors are consistent and typed. Common shapes:
| Status | Meaning |
|---|---|
401 | Missing or invalid token. |
403 | Authenticated, but not permitted (role or tenant scope). |
404 | Not found: also returned instead of leaking cross-tenant resources. |
409 | Conflict or invalid state transition (e.g. joining a locked room). |
Realtime event model
One WebSocket (wss://<host>/presence/ws?token=…) carries typed frames. It numbers frames per tenant for replay (?last_seq=N), reconnects with backoff, and re-delivers still-ringing calls on connect.
| Frame | When |
|---|---|
signal | Targeted at you: incoming call, call accepted/declined/cancelled/missed, private line state. |
presence | A subject went online / offline / available / speaking / in-conference. |
chat | A message on a room you can see. |
activity | Tenant-wide call activity for line bubbles. |
line_state | Scoped line busy-lamp (idle / in_use / held / locked + speaking) for entitled members. |
caption | A live caption line for a call you're on. |
For codegen & agents
The spec is the source of truth
Point your generator or coding agent at /openapi.json. It is versioned in info.version and regenerated on every change, so you can diff it to detect new capabilities. The SDK request and response types are generated from this same file, so the SDK types never drift from the server.