Skip to main content
A session is a conversation with an agent. It maintains conversation history, is pinned to the agent version it starts with, and optionally carries a userId that scopes persistent memory and learned skills for that agent. Memory and learned skills are scoped to agentId + userId. Reuse the same userId with the same agent when you intentionally want memory shared across sessions. Use a different userId to isolate memory. userId is your opaque identifier; it is not used for authentication.

​
Create a session

POST /v1/agents/:agent_id/sessions

const session = await herm.sessions.create("agent_7xK9s2", {
  userId: "org_acme",
  title: "Holiday campaign",
});
When you pass only an agentId, Herm uses the latest agent version at session creation time and pins that resolved version for the lifetime of the session. Future agent updates apply to new sessions, not existing sessions.
ParameterTypeRequiredDescription
userIdstringNoStable identifier for the person, team, organization, workspace, or subject the agent remembers
titlestringNoHuman-readable label for the session
metadataobjectNoKey-value pairs for your own tracking
{
  "id": "session_9kQv32",
  "agentId": "agent_7xK9s2",
  "agentVersion": 3,
  "userId": "org_acme",
  "title": "Holiday campaign",
  "status": "idle",
  "createdAt": "2026-06-11T21:14:02Z"
}

​
List sessions

GET /v1/sessions

const { data, nextCursor } = await herm.sessions.list({
  agentId: "agent_7xK9s2",
  userId: "org_acme",
  limit: 20,
});
ParameterTypeRequiredDescription
agentIdstringNoFilter to sessions for one agent
userIdstringNoFilter to one memory scope
statusstringNoFilter by session status
limitintegerNoPage size, 1–100. Defaults to 20
cursorstringNoPagination cursor from a previous response

​
Get a session

GET /v1/sessions/:session_id
Returns the session state, pinned agent version, metadata, and message history. 
const session = await herm.sessions.get("session_9kQv32");

for (const message of session.messages) {
  console.log(`${message.role}: ${message.content}`);
}

​
Update a session

PATCH /v1/sessions/:session_id

await herm.sessions.update("session_9kQv32", {
  title: "Q3 holiday campaign",
  metadata: { campaign: "holiday" },
});
You can update title and metadata. userId and the pinned agent version do not change after session creation.

​
Archive a session

POST /v1/sessions/:session_id/archive
Archives a session so it no longer appears in active session lists.

​
Delete a session

DELETE /v1/sessions/:session_id
Permanently deletes the session and its conversation history. Persistent memory and learned skills for agentId + userId are unaffected.

​
Endpoint summary

POST /v1/agents//sessions - Create a new session for an agent, optionally passing userId to share memory and learned skills across sessions for that agent and user. GET /v1/sessions - List sessions, filterable by agentId, userId, status, or metadata. GET /v1/sessions/ - Retrieve session state, including status, resolved agent version, userId, metadata, and timestamps. PATCH /v1/sessions/ - Update session metadata or title without changing its userId or resolved agent version. POST /v1/sessions//archive - Archive a session so it no longer appears in active session lists. DELETE /v1/sessions/ - Permanently delete a session and its conversation history.

​
Errors

StatusErrorWhen
400validation_errorInvalid request body
404not_foundAgent or session does not exist
See Errors for the full error reference.