API Reference

ScaiDial exposes three HTTP surfaces:

• Admin (/v1/modules/scaidial/) — tenant-wide configuration and observability. Requires module permissions documented in permissions.
• Portal (/v1/modules/scaidial/me/) — end-user self-service. No special permission; per-row access is gated by ExtensionGrant.
• Internal (/v1/modules/scaidial/sip/...) — called by livekit-sip with a shared secret. Not exposed to callers; documented for completeness in the integration guide.

All routes return the ScaiGrid envelope: {"data": ..., "status": "ok"} or {"error": {"code": ..., "message": ..., "details": ...}}.

Trunks#

GET /trunks#

List trunks for the caller's tenant.

POST /trunks#

Create a trunk. Body:

Returns the created trunk with sync_status="pending". Poll until synced (or error).

PATCH /trunks/{id}#

Update a trunk. Same body as POST; all fields optional. Changes trigger a re-sync.

DELETE /trunks/{id}#

Delete a trunk. Removes the registration on livekit-sip. Fails if any DID references the trunk.

POST /trunks/{id}/resync#

Force a re-sync after an error. Useful when you've fixed credentials on the carrier side.

POST /trunks/probe#

Test a trunk's connectivity without persisting it. Body is the same shape as POST. Returns {"ok": bool, "detail": string}.

DIDs#

GET /dids#

List DIDs for the caller's tenant.

POST /dids#

Create a DID. Body:

PATCH /dids/{id}#

Partial update. enabled is the toggle the UI flips inline.

DELETE /dids/{id}#

Delete a DID.

Extensions#

GET /extensions#

List extensions for the caller's tenant.

POST /extensions#

Create an extension. Body:

PATCH /extensions/{id}#

Partial update.

DELETE /extensions/{id}#

Delete an extension. Fails if any dialplan rule references it.

GET /extensions/{id}/grants#

List grants (who has access to this extension).

POST /extensions/{id}/grants#

Create a grant.

DELETE /extensions/{id}/grants/{grant_id}#

Remove a grant.

Dialplans#

GET /dialplans#

List dialplans for the caller's tenant.

POST /dialplans#

Create a dialplan. Body: {"name": string}.

PATCH /dialplans/{id}#

Rename a dialplan.

DELETE /dialplans/{id}#

Delete. Fails if any DID references it.

GET /dialplans/{id}/rules#

List rules for a dialplan, ordered by priority.

POST /dialplans/{id}/rules#

Create a rule. Body:

PATCH /dialplans/{id}/rules/{rule_id}#

Partial update.

DELETE /dialplans/{id}/rules/{rule_id}#

Delete a rule.

GET /dialplan-pickers#

One fetch, multiple lists — used by the visual builder. Returns {match_types, action_types, dids, extensions, bots, users, voicemail_boxes}.

Active calls#

GET /calls/active#

List calls in state ringing, active, or held. Each call includes its current legs.

GET /calls/{id}#

Single call detail.

GET /calls/history#

Paginated history of ended calls. Filters:

• extension_id — calls where any leg touched this extension
• from_e164 — substring match on caller
• end_reason — exact match
• started_after / started_before — ISO-8601
• limit — capped at 500
• cursor_started_at — keyset pagination

Returns {items: [...], next_cursor_started_at: string | null}.

Per-leg controls#

• POST /legs/{id}/hangup — end the leg
• POST /legs/{id}/hold — mute the leg's audio track
• POST /legs/{id}/unhold — restore
• POST /legs/{id}/transfer — blind transfer. Body: {to_extension, mode: "blind"}. 409 on attended (not yet implemented) or carrier-rejected REFER.

Voicemail#

GET /voicemail#

List voicemail messages. Query: extension_id (filter), only_unheard (bool), limit.

GET /voicemail/{id}/audio#

Stream the recording bytes as audio/wav. Browsers can play this directly via <audio src>.

POST /voicemail/{id}/listened#

Mark listened. Idempotent.

DELETE /voicemail/{id}#

Delete a voicemail.

Forward rules#

GET /extensions/{id}/forward-rules#

List forward rules on an extension.

POST /extensions/{id}/forward-rules#

Create a rule. Body:

DELETE /extensions/{id}/forward-rules/{rule_id}#

Delete.

Tenant policy#

GET /policy#

Read the tenant's policy. Returns defaults if no row exists.

1

{"voicemail_transcript_enabled": false}

PATCH /policy#

Update. Only fields explicitly sent are touched. Stamps updated_by_user_id automatically.

Network info#

GET /network-info#

The four-tuple a carrier needs for whitelisting:

1
2
3
4
5
6

{
  "egress": {"v4": "203.0.113.5", "v6": "2001:db8::1"},
  "sip": {"port": 5060, "transports": ["UDP", "TCP"]},
  "rtp": {"port_start": 10000, "port_end": 10200, "transport": "UDP"},
  "guidance": "..."
}

End-user portal (/me/...)#

Distinct surface for tenant users without admin permission. Per-row access is gated by ExtensionGrant: read operations need any grant role (owner / manage / answer / observe); edit operations need owner.