Sessions
A session is the unit of conversation. It owns its messages, any tool calls the model has emitted, and the running state needed to keep the conversation coherent across turns.
What a session is
In storage, a session is a single row keyed by (userPrincipal, sessionId). The row stores creation timestamp and minimal metadata;
messages and tool calls live in separate tables joined back by
sessionId.
sessionIdstringAn opaque identifier. Treat it as a string — don't parse it.
createdAtnumberUnix timestamp (ms) when the session was created.
Lifecycle
A session is created explicitly by the caller via POST /v1/sessions.
There is no implicit creation from sending a message — if you don't have a
sessionId, you'll get a 404.
Sessions are long-lived by default. There's no automatic timeout, but the team may add TTL-based cleanup in the future. For now, treat sessions as resources you own and clean up when you're done.
A typical chat UI creates one session per "new chat" button click and reuses it for the rest of that conversation. There's no benefit to reusing a session across unrelated topics — start a fresh one and save the model some context cost.
Default agent
If you create a session without a customizations body, no agent is
stored on the session row. The first time you send a message into that
session, the backend falls back to the default agent
(DEFAULT_AGENT_ID, which ships as RfsAgent — the Warehouse Smart
Agent). See Models for what RfsAgent does.
Naming the agent explicitly via customizations.agentId is recommended
so the session's behavior is obvious from its creation call, and so you
have a place to attach extensions later.
Scoping and isolation
Sessions are scoped to the authenticated user. You can only see sessions you created. There is no cross-user access, and tenant admins can't read another user's sessions via the v1 API.
Deletion
DELETE /v1/sessions/:sessionId removes the session row and cascades to
its messages and tool calls. Deletion is hard — there is no soft-delete
or recovery. If you need to audit conversations, export them before
deleting.
Tool calls in flight at deletion time will be orphaned. They won't be resumed and any heartbeats from in-progress callers will be rejected.