Skip to main content
Session objects are typed, aliased values stored in a session’s context. Any workflow processor or external caller can read and write session objects to share state across executions within the same session.

​
Envelope

Every session object is stored as an envelope — a JSON document with the following top-level fields:
FieldTypeDescription
revision_idstringRevision that owns this object.
session_idstringSession that owns this object.
aliasstringUnique name for this object within the session.
updated_atstringISO 8601 timestamp of the last upload_session_object call.
valueobjectThe typed payload. Must contain at minimum "type" as a discriminator.
The value object always begins with a type string that determines the payload shape: 
{
  "revision_id": "rev_001",
  "session_id":  "sess_001",
  "alias":       "my_object",
  "updated_at":  "2026-06-06T10:00:00.000000+00:00",
  "value": {
    "type": "...",
    ...
  }
}

​
Managing Session Objects

OperationDescription
Upload Session ObjectCreate or replace an object (envelope only).
Download Session ObjectRead back the full envelope.
List Session ObjectsList aliases of all objects present in the session.
Uploading an object fires a session_object_modified session event. Deleting it fires session_object_deleted.

​
Types

Some types have additional incremental operations and real-time events beyond the basic upload/download/list.
TypeDescriptionDetails
messageA single generative-AI message (role + content + providers + metadata).See Data Types
messagesAn ordered sequence of message objects representing a conversation log.See Data Types
threadAn append-only stream of structured items. Items live in a separate store with their own API.See thread
graphA mutable property graph of vertices and edges. Elements live in a separate store with their own API.See graph
The thread and graph types are envelope-based: uploading the envelope creates the container, and dedicated commands manage the items or elements. Deleting the envelope via delete_session_object cascades and removes all associated items or elements.