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

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. 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 — is authoritative and is never overwritten. To react to the generated title in real time, watch for the session.title_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.

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:

{
  "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

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}

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 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.

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.

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.

curl -X DELETE "https://api.herm.run/v1/sessions/session_123" \
  -H "x-api-key: $HERM_API_KEY"

Response:

{
  "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.

Getting Started

Agents

Sessions and events

Capabilities

Integrations

Credentials

Resources

Create a session

YOLO mode

Automatic titles

Prewarm an agent

List sessions

Get a session

Update a session

Archive a session

Delete a session

Endpoint summary

Errors

​Create a session

​YOLO mode

​Automatic titles

​Prewarm an agent

​List sessions

​Get a session

​Update a session

​Archive a session

​Delete a session

​Endpoint summary

​Errors

Create a session

YOLO mode

Automatic titles

Prewarm an agent

List sessions

Get a session

Update a session

Archive a session

Delete a session

Endpoint summary

Errors