# Session Endpoints

Endpoints for reading, updating and deleting sessions and their pending and finished tasks.

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/sessions` | List sessions and status |
| `GET` | `/v1/usage` | **local** — 24 h / 7 d / 28 d total token usage across sessions. Since v1.0.11 each per-model row also carries `elapsed_ms` (summed provider round-trip time) and `output_tps` (output tokens per second, computed only over the rows that recorded an elapsed time). Since v1.1.0 the `input` of `claude` and `claude-code` rows includes cache writes (`write`), which those providers report separately; since v1.0.26 each usage record also stores the IDs of the tool calls the response made (not returned here) |
| `POST` | `/v1/session` | **local** — create a session; `{prefix}` defaults to `cli-` |
| `GET` `POST` `DELETE` | `/v1/session/:id` | **local** — one session's full state in one call: `id`, `self_id`, `name`, `role`, `state`, `model`, `reasoning`, `levels`, `count`. `role` (the persona body) replaced `rule` in v1.1.0; `rule` is still returned with the same value and still accepted on `POST` for older clients. `levels` starts with `auto` since v1.1.0 — the model selector then picks the reasoning level per request from the kind of work — and `auto_reasoning` was removed with the global toggle. `POST` is a partial update — `self_id` / `name` / `role` / `model` / `reasoning` are all optional and a field left out (or `null`) is untouched; `model: ""` resets to `auto`, `reasoning` must be one of `levels`. A duplicate `self_id` returns 409. `DELETE` removes the session directory, history, state, and vectors. `GET` also takes `?chat=1` to append the action log under `chat` and `?usage=1` to append per-model token usage under `usage`; both are off by default because the log can be large. Since v1.0.12 the `chat` payload is trimmed: for a task that already reached `done` / `canceled` / `error`, its `tool_*` and `thinking` lines and every assistant line but the last are dropped, so a finished task contributes its outcome rather than its whole trace |
| `POST` | `/v1/session/:id/event` | **local** — publish an event into a session's stream |
| `POST` | `/v1/session/:id/memory` | **local** — one memory operation, picked by `action`: `summary` rebuilds the rolling summary and returns `count`; `compact` drops older messages and returns `removed`; `reset` clears the conversation and returns `removed`, and requires `mode` — `summary` keeps the rolling summary, `all` wipes it too |
| `POST` | `/v1/session/:id/cancel/:task_hash` | Cancel one running task. Returns `{ok, cancelled:true}` when that task hash is running in this process; otherwise (or for `current`) it records a canceled event on the session stream and returns `{ok, cancelled:false, stale:true}` |
| `POST` | `/v1/session/:id/confirm/:confirm_hash` | Resolve an outstanding tool confirmation: `{approve, remember?, allow_turn?, abort?, reason?, password?}`. 410 when the confirmation was already resolved or expired. Approving a confirmation that lists `restricted` paths must come from loopback (403 otherwise) and passes the OS password check with `password` (401 on failure); the check is skipped while the sudo ticket is still cached, which the confirm event reports as `password_cached` |

## Pending and completed tasks

| Method | Path | Description |
|---|---|---|
| `GET` | `/v1/session/:id/task` | List resumable pending (`ask_user` / confirm) tasks. Tasks whose run is still live are excluded — a run refreshes `action:<session_id>:<task_hash>` in ToriiDB every 55 s with a 60 s TTL (v0.35.3), so a task left behind by a closed window or a killed process reappears here within a minute |
| `GET` | `/v1/session/:id/task/:task_hash/questions` | Get a pending task's questions |
| `POST` | `/v1/session/:id/task/:task_hash/resume` | Answer a pending task and resume |
| `DELETE` | `/v1/session/:id/task/:task_hash` | Discard a pending task without answering |
| `GET` | `/v1/session/:id/task/history` | **local** — completed tasks of this session, newest first: `{task_hash, end_at, objective, model, reasoning}` per row. `?keyword=` filters on the objective and the recorded action text |
| `GET` | `/v1/session/:id/task/:task_hash/history` | **local** — the full action record of one completed task, returned as a JSON string under `content`. 404 when that hash has no record |