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

# Sessions

> List, read, rename, and delete conversations on an instance.

A session is one conversation on an instance. An instance holds many sessions, one per thread, and each session keeps its own full history, so you only ever send the new input. These endpoints are served by the gateway running inside the instance.

The gateway keeps no session index of its own. The agent harness owns both the transcript and the list (Hermes' session store, OpenClaw's history), and the gateway projects them on read. So a list or read always reflects the live state of that harness, projected into one shape so you never branch on the harness.

Everything on this page lives on the instance URL, not the hosting API: the base is `https://{instanceId}.agent37.app`, with the same `sk_live_` key sent as the `X-Agent37-Key` header. The platform edge authenticates the key and checks the instance belongs to your workspace, then the gateway answers. See [Instance and preview URLs](/docs/agents-api/urls).

## Endpoints

| Method   | Path                | Returns                                                                                                   |
| -------- | ------------------- | --------------------------------------------------------------------------------------------------------- |
| `GET`    | `/v1/sessions`      | `200` `{ "agent": "...", "data": [...] }`, the harness's session list, newest first                       |
| `GET`    | `/v1/sessions/{id}` | `200` `{ "id", "agent", "active_response_id", "history", "context" }`, the conversation's full transcript |
| `PATCH`  | `/v1/sessions/{id}` | `200` `{ "id", "agent", "renamed" }`, rename a session                                                    |
| `DELETE` | `/v1/sessions/{id}` | `200` `{ "id": "...", "deleted": true }`                                                                  |

<Note>
  You never create a session directly. The first [`POST /v1/responses`](/docs/agents-api/chat) without a `session_id` mints one and returns its id; reuse that id to continue the thread.
</Note>

## Choosing the harness

Every read on this page takes an optional `?agent=` query, `hermes`, `openclaw`, `claude-code`, `codex`, `grok`, or `opencode`, that selects which harness on the instance answers. Omit it (or send it empty) and the instance's configured default harness answers; the response echoes which `agent` it was. An unknown value is `400 validation_error`, and targeting a harness the instance was not provisioned with is `503 agent_unavailable`. Your `agent37-hermes` Cloud instances serve Hermes, so you can leave `?agent=` off.

<Note>
  `codex`, `grok`, and `opencode` mint their own session ids. A client cannot bring an unknown `session_id` on the first turn: `POST /v1/responses` rejects one it did not issue with `400 validation_error` (`param: session_id`). Omit `session_id` to start a thread and reuse the id the response returns. Sessions you start in the instance terminal appear in `GET /v1/sessions?agent=codex` (or `?agent=grok`, `?agent=opencode`) on their own. `grok` stores no editable session title, so `PATCH /v1/sessions/{id}` answers `405 rename_unsupported` there.
</Note>

## The session object

Every row of `GET /v1/sessions` is the same shape regardless of harness: `{ id, title, last_active, message_count, preview }`. The gateway projects the harness's own store into it on read, so a field the harness doesn't track is `null` rather than missing.

<ResponseField name="id" type="string">
  The session id you pass back to `GET`, `PATCH`, and `DELETE /v1/sessions/{id}`, and the `session_id` every response in the conversation carries. 32 hex characters, no prefix.
</ResponseField>

<ResponseField name="title" type="string | null">
  The harness's own editable title, exactly what [rename](#rename-a-session) writes. Hermes generates one on its own shortly after the first completed exchange, so Hermes rows usually carry a title without a rename; an OpenClaw session stays `null` until a rename sets its label.
</ResponseField>

<ResponseField name="last_active" type="number | null">
  When the session was last active, in epoch milliseconds. `null` when the harness reports no timestamp.
</ResponseField>

<ResponseField name="message_count" type="number | null">
  How many messages the session holds. Hermes reports it; OpenClaw does not track it and returns `null`.
</ResponseField>

<ResponseField name="preview" type="string | null">
  The opening of the session's first user message, for list display. Hermes reports it; OpenClaw does not track it and returns `null`.
</ResponseField>

## List sessions

`GET /v1/sessions` returns the harness's sessions, newest first, wrapped in `{ "agent": "...", "data": [...] }`. The list is capped: Hermes returns up to 100 sessions, most recent activity first. OpenClaw returns only the sessions started through this API, drawn from its 1,000 most recently active sessions of any kind. Conversations from OpenClaw's own surfaces, such as its Control UI or a connected channel, count toward that window but are not listed and cannot be read by id through this API. The `agent` names which harness the list is for. Pass `?agent=hermes` or `?agent=openclaw` to pick a harness; omit it for the instance default. The list carries session metadata only, never history, so it stays cheap to poll for a sidebar. A harness without a list API returns `data: []`.

<CodeGroup>
  ```bash curl theme={null}
  curl https://ab12cd34ef.agent37.app/v1/sessions \
    -H "X-Agent37-Key: sk_live_..."
  ```

  ```python python theme={null}
  import requests

  sessions = requests.get(
      "https://ab12cd34ef.agent37.app/v1/sessions",
      headers={"X-Agent37-Key": "sk_live_..."},
  ).json()["data"]
  ```

  ```javascript node theme={null}
  const { data: sessions } = await (await fetch(
    "https://ab12cd34ef.agent37.app/v1/sessions",
    { headers: { "X-Agent37-Key": "sk_live_..." } },
  )).json();
  ```

  ```json response theme={null}
  {
    "agent": "hermes",
    "data": [
      {
        "id": "7f3e0b6c52a949d2b1c4a8e9d0f31726",
        "title": "EV makers memo",
        "last_active": 1781049642000,
        "message_count": 4,
        "preview": "Research the top 3 EV makers, write a memo."
      }
    ]
  }
  ```
</CodeGroup>

## Retrieve a session with history

`GET /v1/sessions/{id}` returns `{ "id", "agent", "active_response_id", "history", "context" }`: `history` is the full transcript, in order, projected from the harness. You read it for display or audit; you never resend it, because the session already holds it. An unknown id returns an empty `history` rather than a `404`, because the harness owns whether a session exists. Pass `?agent=` to pick the harness.

<ResponseField name="active_response_id" type="string | null">
  The id of the response currently running on the session, or `null` when it is idle. The harness writes a turn's messages at turn end, so while this is set the running turn is normally **not** in `history` yet. Follow it live with [`GET /v1/responses/{id}/stream`](/docs/agents-api/streaming#reconnect-after-a-drop). This is how a client that lost its state (page reload, new device) rediscovers a running turn and reattaches. Two timing edges: right at turn end, one read can briefly show the finished turn in `history` and its id still here; reattaching is still correct, the replay just ends immediately. And once it reads `null` the transcript is complete.
</ResponseField>

<ResponseField name="context" type="object | null">
  The session's last reported context window: `{ used_tokens, window_tokens }`, the tokens occupying the model's window against the window's size. `null` until a turn reports one. The gateway keeps this value in memory rather than in the harness's store, for at most 1,000 sessions, so it is `null` again after a gateway restart (or once 1,000 other sessions have reported since) until the next turn reports one.
</ResponseField>

Each entry in `history` is a message:

<ResponseField name="id" type="string">
  The message id. Treat it as opaque; it uses a different format from session and response ids.
</ResponseField>

<ResponseField name="session_id" type="string">
  The session the message belongs to.
</ResponseField>

<ResponseField name="role" type="string">
  `user`, `assistant`, or `system`.
</ResponseField>

<ResponseField name="content" type="string">
  The message text.
</ResponseField>

<ResponseField name="thinking" type="string">
  The assistant's reasoning for that turn, when the agent recorded any. Absent otherwise.
</ResponseField>

<ResponseField name="created_at" type="number">
  When the message was created, in epoch milliseconds.
</ResponseField>

<CodeGroup>
  ```bash curl theme={null}
  curl https://ab12cd34ef.agent37.app/v1/sessions/7f3e0b6c52a949d2b1c4a8e9d0f31726 \
    -H "X-Agent37-Key: sk_live_..."
  ```

  ```json response theme={null}
  {
    "id": "7f3e0b6c52a949d2b1c4a8e9d0f31726",
    "agent": "hermes",
    "active_response_id": null,
    "context": { "used_tokens": 22600, "window_tokens": 256000 },
    "history": [
      {
        "id": "hermes:7f3e0b6c52a949d2b1c4a8e9d0f31726:1",
        "session_id": "7f3e0b6c52a949d2b1c4a8e9d0f31726",
        "role": "user",
        "content": "Research the top 3 EV makers, write a memo.",
        "created_at": 1781049601000
      },
      {
        "id": "hermes:7f3e0b6c52a949d2b1c4a8e9d0f31726:2",
        "session_id": "7f3e0b6c52a949d2b1c4a8e9d0f31726",
        "role": "assistant",
        "content": "Here is the memo...",
        "thinking": "Comparing deliveries, margins, and charging networks...",
        "created_at": 1781049642000
      }
    ]
  }
  ```
</CodeGroup>

## Rename a session

`PATCH /v1/sessions/{id}` sets a session's title, writing it straight into the harness's own store, and returns `{ "id", "agent", "renamed" }`. `renamed` is `false` when no session matched the id. Send the new title in the body:

<ParamField body="title" type="string" required>
  The new title. Cannot be empty. Titles are unique on both harnesses: a title already used by another session returns `409 title_conflict`. Hermes also caps the length; an over-long title returns `400 validation_error`.
</ParamField>

Both harnesses support rename: Hermes writes the title into its session database; OpenClaw stores it as the session's label. A harness with no editable title would return `405 rename_unsupported`; none of the shipped harnesses does. Pass `?agent=` to pick the harness.

<CodeGroup>
  ```bash curl theme={null}
  curl -X PATCH https://ab12cd34ef.agent37.app/v1/sessions/7f3e0b6c52a949d2b1c4a8e9d0f31726 \
    -H "X-Agent37-Key: sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{ "title": "EV makers memo" }'
  ```

  ```json response theme={null}
  { "id": "7f3e0b6c52a949d2b1c4a8e9d0f31726", "agent": "hermes", "renamed": true }
  ```
</CodeGroup>

## Delete a session

`DELETE /v1/sessions/{id}` is a best-effort removal from the harness's store and returns `{ "id": "...", "deleted": true|false }`. `deleted` is `true` when a transcript was removed and `false` when nothing matched the id, so the call is idempotent: repeating it simply returns `deleted: false` rather than erroring. On Hermes the transcript is removed from its session database; on OpenClaw the session leaves its list and OpenClaw archives the transcript off its active path. Pass `?agent=` to pick the harness.

<CodeGroup>
  ```bash curl theme={null}
  curl -X DELETE https://ab12cd34ef.agent37.app/v1/sessions/7f3e0b6c52a949d2b1c4a8e9d0f31726 \
    -H "X-Agent37-Key: sk_live_..."
  ```

  ```json response theme={null}
  { "id": "7f3e0b6c52a949d2b1c4a8e9d0f31726", "deleted": true }
  ```
</CodeGroup>

<Warning>
  Deleting a session removes the conversation and its history from the harness and forgets the session's `context`, but leaves the instance (its files, memory, and connected accounts) untouched. The per-turn response receipts are in-memory and short-lived; they expire on their own.
</Warning>

## One turn at a time

A session runs one response at a time. Posting new input while a turn is in flight returns `409 session_busy`, normally with the running response's id in `error.response_id`. Reattach to it with [`GET /v1/responses/{id}/stream`](/docs/agents-api/streaming#reconnect-after-a-drop), cancel it with [`POST /v1/responses/{id}/cancel`](/docs/agents-api/chat), or start the new input on another session. Two sessions on the same instance run independently.

To see which models a harness can run, and to set the model per turn, see [Models](/docs/agents-api/models). For the readiness probe an app polls after create or start, see [Health & version](/docs/agents-api/health).