What is a session?
A session is a single recorded meeting or conversation. It belongs to a workspace, has one or more audio recordings attached, and produces a transcript and summary when processing is complete.Session states
Key endpoints
Create a session
POST /api/sessions
id.
Get session detail
GET /api/sessions/{session_id}
Returns the session envelope (metadata, capabilities, summaries list, and so on) when the caller is a workspace member, owner, or holds an accepted share. 401 Unauthorized when the caller is not authenticated (including an expired access token — the web client refreshes and retries). 403 Forbidden when the caller is signed in but is not a member of the session’s workspace and has no other access path (session home shows a request-access landing).
Recording state is tracked in Redis. Browser recorders are notified over the moderator SSE stream; hardware boards pick up commands on the next heartbeat.
POST /api/sessions/{session_id}/start— attach selected Meld devices, open a live track for each, and queuestart_recording({ session_id, track_id }). The web client starts its own mic track afterwards if the user opted in.POST /api/sessions/{session_id}/stop— queuestop_recordingto attached devices and notify browser recorders.GET /api/sessions/{session_id}/live-sources— live browser tracks and hardware devices currently feeding the session.PUT /api/sessions/{session_id}/recording-status— set status (recording,paused,inactive); body{ "status": "…" }; session or workspace owner only (403otherwise). Setting status viaGET …/recording-status?status=still works for older clients but is deprecated.
device_ids may be empty when only this browser will record.
Upload audio chunks
POST /api/sessions/{session_id}/chunks
Chunks are sequentially numbered (seq=1, seq=2, …). Each chunk is queued for transcription immediately, giving live partial transcripts in the moderator view.
Limits:
- No hard size limit per chunk, but keep chunks under ~10 MB for reliability
- Chunks must be sequential. If a sequence number is missing at the final chunk, the track waits in
finalisingfor the late chunk and the stale-track sweeper stitches it after 120 s with what arrived 500/409responses are safe to retry;422means the audio could not be decoded, so the client drops that chunk
Finalise a session
POST /api/sessions/{session_id}/finalize
Triggers stitching of all chunks into one audio file, then queues the final transcription job. After this point no more chunks can be uploaded.
Get session details
GET /api/sessions/{session_id}
Returns the session with its current state, transcript (if complete), summary (if complete), and job statuses.
List sessions
GET /api/sessions?workspace_id=...
Paginated. Returns sessions for a workspace ordered by created_at descending.
Recording ownership
Only one client can record at a time per session. When recording starts, the API stores a recording owner token in Redis (TTL 1 hour). If another client tries to start recording, they see a “someone else is recording — take over?” prompt. The token expires automatically after 1 hour to handle crashes/disconnects. Ownership is released when recording is stopped normally.Live transcript
While recording, chunk transcripts appear in the moderator view via WebSocket as each chunk job completes. These are preliminary — the final full-audio transcription replaces them once finalisation is complete.Transcript & summary access
GET /api/sessions/{session_id}/transcript— full transcript text with speaker labels and timestampsGET /api/sessions/{session_id}/summary— AI-generated summary (available after finalisation + summarisation)