> ## Documentation Index > Fetch the complete documentation index at: https://docs.herm.run/llms.txt > Use this file to discover all available pages before exploring further. # Sessions > Create, list, inspect, update, archive, and delete agent sessions. A session is a conversation with an agent. It records the latest agent version at creation time and is scoped to a `subjectId`, your stable identifier for the person, team, organization, workspace, or other entity the agent should remember. Session statuses are `idle`, `running`, `waiting_on_human`, and `archived`. `waiting_on_human` means the active turn requires a response such as tool approval or clarification. Default session listing excludes archived sessions. ## Create a session ``` POST /v1/sessions ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/sessions" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "agentId": "agent_123", "subjectId": "user_123", "role": "readonly", "title": "Holiday campaign", "yoloMode": false, "metadata": { "campaignId": "camp_456" } }' ``` | Field | Type | Required | Description | | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `agentId` | string | Yes | Agent to start a session from. | | `subjectId` | string | Yes | Stable memory/identity scope for this agent. | | `role` | string | No | Named role from the session's recorded agent version. When set, the role's tool policies are used for approval and denial decisions. | | `title` | string | No | Human-readable session label. If omitted, the agent auto-generates one after the first turn. | | `yoloMode` | boolean | No | Defaults to `false`. When `true`, approval prompts for `always_ask` tools are accepted automatically for this session. | | `metadata` | object | No | String-keyed metadata values for your own tracking. | Creating a session consumes one conversation from the agent's per-user allowance. The default is 5 conversations per stable `subjectId` per fixed 60-second window. Reuse the same `subjectId` for the same authenticated user; do not generate a new value for each session. See [Rate limits](/api-reference/rate-limits). Session creation always resolves and records the agent's latest version. Historical versions cannot be selected for a new session. If `role` is omitted, the session uses the agent version's top-level `tools` configuration. If `role` is provided and the recorded agent version does not define that role, session creation returns `400 validation_error`. ### YOLO mode Set `yoloMode: true` when a session should run without stopping for tool approval prompts. YOLO mode only auto-accepts tools whose resolved permission policy is `always_ask`; tools configured as `always_deny` or disabled with `enabled: false` are still denied before execution. Use it for trusted autonomous sessions where your product has already collected broad consent. Leave it unset or `false` when users should approve sensitive actions interactively. ### Automatic titles If you omit `title`, the agent automatically generates a short, descriptive title from the first exchange once the session's first turn completes, and stores it on the session's `title`. A `title` you provide here — or set later via [update](#update-a-session) — is authoritative and is never overwritten. To react to the generated title in real time, watch for the [`session.title_updated`](/api-reference/events-reference#sessiontitle_updated) event on the session's event stream. ## Prewarm an agent ``` POST /v1/sandboxes/warm ``` Starts preparing an agent for a subject before a session exists. Session creation also begins this preparation automatically, but calling this endpoint earlier can reduce first-response latency. Call it as soon as you know a conversation is likely to start — for example when the user opens your chat UI — then create the session as usual. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/sandboxes/warm" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "agentId": "agent_123", "subjectId": "user_123" }' ``` | Field | Type | Required | Description | | ----------- | ------ | -------- | --------------------------------------------------------------------------------------------- | | `agentId` | string | Yes | Agent the upcoming session will be created from. | | `subjectId` | string | Yes | Subject the upcoming session will use. Must match the values you pass to `POST /v1/sessions`. | The request returns `202 Accepted` immediately and preparation continues in the background. Relevant response fields are: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "sandbox.warm", "status": "warming", "reason": null, "agentId": "agent_123", "subjectId": "user_123" } ``` Prewarming is an idempotent hint, so it is always safe to call: * Repeated calls for the same agent and subject are safe. * No session or conversation history is created. * Use the same `agentId` and `subjectId` when creating the upcoming session. ## List sessions ``` GET /v1/sessions ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/sessions?agentId=agent_123&limit=20&offset=0" \ -H "x-api-key: $HERM_API_KEY" ``` | Query | Type | Description | | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `agentId` | string | Filter by agent ID. | | `agent` | string | Alias for `agentId`. If both are provided they must match. | | `subjectId` | string | Filter by subject ID. | | `subject` | string | Alias for `subjectId`. If both are provided they must match. | | `status` | string | Filter by `idle`, `running`, or `archived`. `waiting_on_human` can appear in responses but is not currently accepted as a list filter. If omitted, archived sessions are excluded. | | `limit` | integer | Page size, 1 to 100. Defaults to `50`. | | `offset` | integer | Offset for pagination. Defaults to `0`. | ## Get a session ``` GET /v1/sessions/{sessionId} ``` ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl "https://api.herm.run/v1/sessions/session_123" \ -H "x-api-key: $HERM_API_KEY" ``` Returns the session state, recorded agent version, metadata, timestamps, and the latest `usage` snapshot when the agent has completed at least one turn. Session `usage` aggregates token counts, model calls, and estimated cost across completed turns. It also stores `context_max` so UIs can show aggregate tokens as a percentage of the model context window. Per-turn context and latency are emitted on terminal events in the [event stream](/api-reference/stream-events#usage-snapshots) for direct export to Langfuse or another observability backend. ## Update a session ``` POST /v1/sessions/{sessionId} ``` Updates the session title, YOLO mode, and/or metadata. The next approval decision reads the latest `yoloMode` value. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/sessions/session_123" \ -H "Content-Type: application/json" \ -H "x-api-key: $HERM_API_KEY" \ -d '{ "title": "Q3 holiday campaign", "yoloMode": true, "metadata": { "campaign": "holiday" } }' ``` | Field | Type | Required | Description | | ---------- | ------- | -------- | ----------------------------------------------------------------------------------------- | | `title` | string | No | New human-readable session label. | | `yoloMode` | boolean | No | Enables or disables automatic acceptance of `always_ask` tool approvals for this session. | | `metadata` | object | No | Replaces the session metadata object. | At least one of `title`, `yoloMode`, or `metadata` is required. ## Archive a session ``` POST /v1/sessions/{sessionId}/archive ``` Archives an inactive session so it no longer appears in default session lists. Already archived sessions return the session response unchanged. Sessions with a running or `waiting_on_human` turn return `409`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X POST "https://api.herm.run/v1/sessions/session_123/archive" \ -H "x-api-key: $HERM_API_KEY" ``` ## Delete a session ``` DELETE /v1/sessions/{sessionId} ``` Permanently deletes an inactive session and its event history. Sessions with a running or `waiting_on_human` turn return `409`. ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} curl -X DELETE "https://api.herm.run/v1/sessions/session_123" \ -H "x-api-key: $HERM_API_KEY" ``` Response: ```json theme={"theme":{"light":"github-light","dark":"github-dark"}} { "object": "agent.session_deleted", "id": "session_123", "deleted": true } ``` ## Endpoint summary | Method | Path | Description | | -------- | ---------------------------------- | ------------------------------------------------------- | | `POST` | `/v1/sandboxes/warm` | Prepare an agent and subject ahead of session creation. | | `POST` | `/v1/sessions` | Create a session from an agent for a subject. | | `GET` | `/v1/sessions` | List sessions. | | `GET` | `/v1/sessions/{sessionId}` | Retrieve a session. | | `POST` | `/v1/sessions/{sessionId}` | Update session title, YOLO mode, or metadata. | | `POST` | `/v1/sessions/{sessionId}/archive` | Archive a non-running session. | | `DELETE` | `/v1/sessions/{sessionId}` | Delete a non-running session and its event history. | ## Errors | Status | Error | When | | ------ | ------------------ | --------------------------------------------------------------------------------------------------------- | | `400` | `validation_error` | Invalid request body or query. | | `404` | `not_found` | Agent or session does not exist. | | `409` | `invalid_state` | The session state does not allow the requested operation. | | `429` | `rate_limited` | The agent's per-user conversation allowance is exhausted. Retry after the response's `Retry-After` delay. |