Manage sessions
Create, list, get, update, and delete sessions with full SessionState schema
These endpoints let you create, list, retrieve, update, and delete the sessions that hold a conversation and its full history — messages, tool calls, jobs, checkpoints, and version metadata — so a chat can outlive a single request and be resumed later. Start here to open a session before you run any turns against it in Message execution, and to inspect or tear one down afterward.
Sessions CRUD
A session stores a multi-turn conversation with its tool calls, jobs, artifacts and version metadata. Each write increments its version.
Try it live: Open the Interactive API Reference to browse and test all sessions endpoints.
List Sessions
GET /api/v1/sessions returns the caller's sessions, most recently active first (reference).
| Query | Default | Meaning |
|---|---|---|
limit | 50 | Page size, capped at 100 |
cursor | none | The nextCursor from the previous page |
organizationId | none | Only sessions in this organization |
The response is { sessions, hasMore, nextCursor? }; each summary carries id, title, messageCount, createdAt, updatedAt and lastActiveAt.
Create Session
POST /api/v1/sessions creates an empty session and returns 201 with { id, createdAt, chatId? } (reference).
| Body field | Meaning |
|---|---|
title | Optional display title |
clientId | Seeds the version vector; defaults to web_<timestamp> |
chatId | Optional chat to bind the session to; echoed back only if the bind succeeds |
config.provider, config.model, config.tools | Optional runtime settings stored in the session state |
Get Session
GET /api/v1/sessions/:sessionId returns { id, title, version, schemaVersion, state, messageCount, createdAt, updatedAt, lastActiveAt }, where state is the full SessionState below (reference).
Update Session
PUT /api/v1/sessions/:sessionId merges state and replaces title, then increments version (reference). The write is conditioned on the version it read, so a concurrent writer gets 409 and should re-read before retrying.
Delete Session
DELETE /api/v1/sessions/:sessionId deletes the session and returns { "success": true } (reference).
SessionState Schema
The main fields of the session state (the full type is SessionState in @pleach/core):
Session state dates (createdAt, updatedAt, lastActiveAt) arrive as ISO 8601 strings, not Date objects, because the state is stored as JSONB in PostgreSQL.
Read next
- Sessions Overview — architecture and quick start
- Message execution — SSE streaming
- Sync protocol — version vectors
- Checkpoints — snapshot and rollback
Was this page helpful?