API reference

All endpoints are mounted at /v1/modules/scaiecho/ and authenticate with the standard ScaiGrid bearer token. WebSocket routes accept the same bearer from the token= query parameter or the Authorization header. Responses use ScaiGrid's standard envelope ({ "data": ... } for success, { "error": ... } for failures).

Health#

GET /healthz#

Liveness check. Always returns { "status": "ok", "module": "scaiecho" }. Unauthenticated.

GET /readyz#

Readiness check. Returns status, module, and the current rollout phase. The platform health aggregator probes this. Unauthenticated.

Batch transcription#

POST /transcribe#

Multipart upload. Returns the transcript inline for short audio, or 202 Accepted with a job_id for long audio.

Inline response (200 OK):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
  "data": {
    "job_id": "...",
    "transcript": "...",
    "backend_used": "A",
    "language_detected": "en",
    "audio_duration_ms": 12500,
    "audio_bytes": 400000
  }
}

Async response (202 Accepted):

1
2
3
4
5
6
7
8

{
  "data": {
    "job_id": "...",
    "status": "queued",
    "audio_bytes": 14580000,
    "note": "Long-form transcribe runs asynchronously. Poll GET /v1/modules/scaiecho/transcribe/jobs/{id}"
  }
}

Permission: scaiecho:transcribe.

GET /transcribe/jobs/{job_id}#

Poll an async transcribe job. The transcript is inline on the response when status == "completed" — STT outputs are text, no S3 fetch needed.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "data": {
    "job_id": "...",
    "status": "completed",
    "transcript": "...",
    "backend_used": "A",
    "language_detected": "en",
    "audio_duration_ms": 612000,
    "audio_bytes": 14580000,
    "created_at": "...",
    "completed_at": "...",
    "status_reason": null
  }
}

Status values: queued, running, completed, failed. Cross-tenant or cross-user reads return 404 (deliberate, to avoid leaking job existence).

Permission: scaiecho:transcribe.

WebSocket streaming#

WS /stream/transcribe#

Real-time STT over WebSocket. Client opens the WS with ?token=... or an Authorization header, sends an open JSON frame, pushes binary audio frames, then close.

Open frame (client → server):

1
2
3
4
5
6
7
8
9

{
  "type": "open",
  "language_hint": "en",
  "media_type": "audio/wav",
  "backend_preference": "any",
  "chunk_seconds": 5.0,
  "sample_rate": 16000,
  "diarize": false
}

Server frames:

The speaker_label field is omitted when no diarization label is available. Close codes: 4401 (unauthorized), 4403 (forbidden), 4400 (bad request), 4502 (backend unavailable), 4500 (server error).

Permission: scaiecho:transcribe. Diarization additionally requires scaiecho:diarize.

WebRTC streaming#

Status: signalling and lifecycle ship end-to-end. The audio-decode plane (av.AudioFrame → backend dispatcher) is still in progress. Sessions create, SDP exchanges, ICE trickles, control WebSocket attaches — but no audio reaches the backend yet, so no transcript deltas come back. Use the WebSocket streaming endpoints for production until this caveat is removed.

All WebRTC endpoints are under /stream/transcribe/webrtc/.

POST /stream/transcribe/webrtc/sessions#

Create a session. Returns 201 Created:

1
2
3
4
5
6
7
8

{
  "data": {
    "session_id": "...",
    "ice_servers": [{ "urls": ["stun:..."] }],
    "expires_at": "...",
    "control_ws_url": "/v1/modules/scaiecho/stream/transcribe/webrtc/sessions/{id}/control"
  }
}

Body fields: language_hint (2-char), media_type (default audio/wav), backend_preference, chunk_seconds (0.5–60.0), sample_rate (8000–48000), ice_servers (optional tenant-supplied ICE config).

Permission: scaiecho:transcribe.

POST /stream/transcribe/webrtc/sessions/{id}/offer#

Apply client SDP offer, return our answer.

1

{ "sdp": "v=0...", "type": "offer" }

Returns { "data": { "sdp": "...", "type": "answer" } }. Errors: SCAIECHO_WEBRTC_UNAVAILABLE (501, aiortc not installed), SCAIECHO_WEBRTC_SESSION_NOT_FOUND (404), SCAIECHO_WEBRTC_SESSION_STATE_LOST (410).

POST /stream/transcribe/webrtc/sessions/{id}/ice-candidates#

Trickle an ICE candidate. Body: { "candidate": "...", "sdp_mid": "...", "sdp_mline_index": 0 }. Returns 204 No Content.

DELETE /stream/transcribe/webrtc/sessions/{id}#

Tear down the peer connection and mark the session closed. Returns 204 No Content.

WS /stream/transcribe/webrtc/sessions/{id}/control#

Control plane for the WebRTC session. Server emits delta JSON frames as the dispatcher produces transcript records. The client can send {"type": "close"} to tear the session down early.

Speakers#

GET /speakers#

List speakers visible to the caller.

Query parameters: language (ISO 639-1), scope (global, tenant, user), enrollment_status (pending, ready, failed, evicted), limit (1–200, default 50).

Permission: scaiecho:enroll.

GET /speakers/{speaker_id}#

Fetch one speaker. Permission: scaiecho:enroll.

POST /speakers#

Enroll a speaker. Multipart upload:

Returns 201 Created with the new speaker profile plus a preflight block, an enrolled_on node-id list, and optionally enroll_errors per node or a note if no pyannote node is online. Permission: scaiecho:enroll.

PATCH /speakers/{speaker_id}#

Update mutable fields. Body: { "display_name": "...", "description": "..." }. Scope and ownership are locked at create. Permission: scaiecho:enroll.

DELETE /speakers/{speaker_id}#

Erase a speaker — Art. 17 fan-out. Deletes blobs, writes an audit row, tombstones the row, evicts the embedding from every replica.

1
2
3
4
5
6
7
8
9

{
  "data": {
    "audit_id": "...",
    "speaker_id": "...",
    "blob_bytes_deleted": 480000,
    "error_summary": null,
    "completed_at": "..."
  }
}

Permission: scaiecho:enroll.

GET /speakers/{speaker_id}/warm#

Inspect current enrollment fan-out.

1
2
3
4
5
6
7
8

{
  "data": {
    "speaker_id": "...",
    "warm_node_ids": ["..."],
    "candidate_node_ids": ["..."],
    "stale_node_ids": []
  }
}

Permission: scaiecho:enroll.

POST /speakers/{speaker_id}/warm#

Proactive re-enrollment fan-out. Body: { "node_ids": [] } (empty for all candidates). Returns per-node outcomes plus skipped_not_candidate for any requested ids that weren't pyannote candidates. Permission: scaiecho:enroll.

Tenant policy#

GET /tenant-policy#

Read the resolved policy. Lazy-creates a row from tier defaults on first read. Permission: scaiecho:admin.

1
2
3
4
5
6
7
8
9

{
  "data": {
    "tenant_id": "...",
    "allowed_backends": "AB",
    "default_backend": "B",
    "created_at": "...",
    "updated_at": "..."
  }
}

PATCH /tenant-policy#

Update allowed set and/or default backend.

1

{ "allowed_backends": "AB", "default_backend": "A" }

allowed_backends matches ^(A|B|AB|BA)$. default_backend is A or B and must be in the allowed set. Permission: scaiecho:admin.

Errors#

ScaiEcho returns ScaiGrid's standard error envelope. Specific codes:

MCP tool#

ScaiEcho registers one tool with the MCP catalog:

• scaiecho.transcribe — base64 audio in, transcript and metadata out. Backend selection is hidden from MCP callers; tenant policy decides A or B. Required permission: scaiecho:transcribe.