Get one session's full history

GET /v1/sessions/:id

The primary history-read endpoint: session metadata + every persisted message in chronological order + the session's open interaction-queue questions. A client renders history from this, then follows the live turn (when is_streaming is true) by subscribing to the WS chat channel keyed by this session id.

Response body

{ "id": "chat_abc", "title": "BTC analysis", "origin": "web", "kind": "chat", "created_at_ms": 1747000000000, "updated_at_ms": 1747000500000, "message_count": 2, "has_unseen_completion": true, "completion_settled_at_ms": 1747000500000, "messages": [ { "id": 1, "role": "user", "content": "analyze BTC", "ts_ms": 1747000000000, "metadata": null }, { "id": 2, "role": "assistant", "content": "…", "ts_ms": 1747000400000, "metadata": { "segments": [ { "kind": "text", "text": "…" }, { "kind": "tool", "toolId": "call_1" } ], "toolCalls": [ { "id": "call_1", "name": "get_quote", "args": { "symbol": "BTC" }, "ok": true, "result": "…", "duration_ms": 812 } ] } } ], "is_streaming": false, "pending_questions": [] }

Notes

metadata is role-dependent. Assistant rows carry segments (the ordered render plan: {kind:"text",text} | {kind:"tool",toolId} | {kind:"block",block} where block is a UI-block envelope), toolCalls (one record per tool call, referenced by toolId), and optionally interrupted: true when the turn was stopped early. User rows may carry attachments (also lifted to a top-level attachments field on the message), interjection: true for mid-turn steering messages (dedupe against the stream's user_interjection event via ts_ms), and voice-input keys. Rows predating metadata persistence have metadata: null — render content as plain markdown. pending_questions mirrors the pending_question_added stream event's shape; answer them via POST /v1/interactions/:id/answer. Returns 404 {"error":"session_not_found"} for an unknown id. completion_settled_at_ms identifies the completion represented by has_unseen_completion so stale reads cannot restore an acknowledged result.