Skip to main content
Sessions are exposed in the API as threads. Every deployment starts with a default thread; create more for parallel or scoped conversations. Messages are posted with Send Message, and activity streams over SSE.

​
Create a thread

POST /v1/deployments/:deployment_id/threads

const thread = await herm.threads.create("dep_7xK9s2", {
  title: "Holiday campaign",
});
ParameterTypeRequiredDescription
titlestringNoHuman-readable label for the thread
{
  "thread_id": "thr_9kQv32",
  "deployment_id": "dep_7xK9s2",
  "title": "Holiday campaign",
  "status": "idle",
  "created_at": "2026-06-11T21:14:02Z"
}
A new thread starts with empty conversation history; the deployment’s memory and filesystem carry over.

​
List threads

GET /v1/deployments/:deployment_id/threads

const { data, next_cursor } = await herm.threads.list("dep_7xK9s2", {
  limit: 20,
});
ParameterTypeRequiredDescription
limitintegerNoPage size, 1–100. Defaults to 20
cursorstringNoPagination cursor from a previous response
{
  "data": [
    {
      "thread_id": "thr_default_8a1",
      "title": "Default",
      "status": "idle",
      "message_count": 42,
      "last_activity_at": "2026-06-11T20:58:11Z"
    }
  ],
  "next_cursor": null
}

​
Get a thread

GET /v1/deployments/:deployment_id/threads/:thread_id
Returns the thread plus its message history. 
const thread = await herm.threads.get("dep_7xK9s2", "thr_default_8a1");

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

{
  "thread_id": "thr_default_8a1",
  "title": "Default",
  "status": "idle",
  "messages": [
    {
      "role": "user",
      "content": "Write a storyboard for a 30-second demo",
      "created_at": "2026-06-11T20:55:03Z"
    },
    {
      "role": "agent",
      "content": "Done — saved to storyboard.md with 6 shots.",
      "run_id": "run_4mPx81",
      "created_at": "2026-06-11T20:58:11Z"
    }
  ]
}

​
Update a thread

PATCH /v1/deployments/:deployment_id/threads/:thread_id

await herm.threads.update("dep_7xK9s2", "thr_9kQv32", {
  title: "Q3 holiday campaign",
});

​
Delete a thread

DELETE /v1/deployments/:deployment_id/threads/:thread_id
Deletes the thread and its conversation history. Memory and files are unaffected. The default thread can’t be deleted. 
await herm.threads.delete("dep_7xK9s2", "thr_9kQv32");

​
Errors

StatusErrorWhen
400validation_errorInvalid body, or deleting the default thread
404not_foundDeployment or thread does not exist
See Errors for the full error reference.