Skip to main content

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
Returns the new session with its 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 queue start_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 — queue stop_recording to 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 (403 otherwise). Setting status via GET …/recording-status?status= still works for older clients but is deprecated.
Start body:
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 finalising for the late chunk and the stale-track sweeper stitches it after 120 s with what arrived
  • 500/409 responses are safe to retry; 422 means 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 timestamps
  • GET /api/sessions/{session_id}/summary — AI-generated summary (available after finalisation + summarisation)
Summaries are user-triggered — they do not generate automatically. A moderator must request summarisation from the session page.