Sessions

Create, list, inspect, update, archive, and delete agent sessions.

A session is a conversation with an agent. It records the production 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.
preview	boolean	No	Defaults to false. When true, pins the session to the newest unpromoted version for local integration testing.
tag	string	No	Pins the session to the version targeted by this development tag. Mutually exclusive with preview: true.
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 resolves and records the agent’s production version. Publishing a newer version does not affect new sessions until you promote it.

Preview the newest version

Set preview: true when your local application needs to test the newest unpromoted agent version end to end:

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": "local-development",
    "preview": true
  }'

A preview session remains pinned to that version while normal sessions continue following production. Your application can use its existing event stream and custom-tool handler to execute real local tool code before promotion. Use a separate development subjectId so preview activity does not share a subject sandbox with production traffic.

Run a development tag

Use a development tag when local testing needs a stable name instead of always selecting the newest version:

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": "local-feature-x",
    "tag": "feature-x"
  }'

The tag is resolved once during session creation. Moving or deleting the tag does not change existing sessions. Use a development-only subjectId so tagged sessions do not replace a production subject’s sandbox when their versions differ.

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. Otherwise, runtime acquisition begins with the session’s first turn. Prewarming always prepares the production version.

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.