Sessions API

A session is the top-level recording unit in Looma.

Lifecycle

Sessions usually move through these states:

1. recording while events are being captured.
2. processing after record_stop.
3. replay_ready when replay metadata is available.
4. failed if recording or processing cannot complete.

Start a session

record_start creates a session and returns a sessionId.

{
  "name": "Add JWT auth with refresh token",
  "harness": "claude-code",
  "workspaceName": "api-service"
}

Stop a session

record_stop closes the active recording and triggers replay processing.

{
  "sessionId": "2c0e9a50-9f8d-4e74-9cf8-4cb4c9b678e1",
  "finalOutput": {
    "title": "Final implementation summary",
    "content": "Implemented JWT auth with refresh-token rotation and verified it with bun test.",
    "format": "markdown"
  }
}

finalOutput is optional, but recommended. When present, Looma records it as a first-class replay event so the session detail page can show the agent's final answer beside the replay context.

Public replay route

Every completed session has a canonical replay route:

/sessions/{sessionId}

Use this URL for handoff, review, and sharing. It is separate from internal API routes such as replay data fetching.

Replay data

Replay data includes the session record, normalized events, Needs Review markers, chapters, behavior summary, notes, final output, and redaction summary.