> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kair.is/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Session lifecycle — creation, recording, transcription, and finalisation.

## 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

```
created → recording → paused → finalising → completed
                                     ↓
                                  failed
```

| State        | What it means                                 |
| ------------ | --------------------------------------------- |
| `created`    | Session exists, no recording started          |
| `recording`  | Audio is actively being captured              |
| `paused`     | Recording paused, can be resumed              |
| `finalising` | Recording stopped, transcription jobs running |
| `completed`  | Transcript and summary available              |
| `failed`     | One or more transcription jobs failed         |

## Key endpoints

### Create a session

`POST /api/sessions`

```json theme={null}
{
  "workspace_id": "...",
  "title": "Town Hall — May 2026",
  "planned_headcount": 40
}
```

Returns the new session with its `id`.

### Start / stop recording

Recording state is tracked in Redis and broadcast via WebSocket to all connected clients.

* `PUT /api/sessions/{session_id}/recording-status` — set status (`recording`, `paused`, `inactive`)

The web app uses WebSocket (not polling) to display the current recording state to all open tabs.

### 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 — gaps cause stitching errors

### 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 (with diarisation) 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.