Skip to main content
A thread session object is an append-only stream of structured items. The envelope marks the object as a thread and holds optional metadata about it; items themselves live in a separate store with their own read/write commands.

​
Envelope

Upload a thread envelope with upload_session_object, setting value.type to "thread": 
{
  "type": "thread",
  "thread": {
    "attributes": {
      "id": "uuid-for-tracking",
      "created_at": "2026-05-28T12:00:00.000000+00:00",
      "name": "Onboarding conversation",
      "description": "..."
    },
    "metadata": {}
  }
}
The thread object inside value carries two optional sub-fields:
FieldTypeDescription
attributesobjectOptional named metadata: id, created_at, name, description.
metadataobjectOptional arbitrary JSON.
The envelope is read back as-is via download_session_object. No items are included in that response — items are fetched exclusively through the thread item commands.

​
Thread Items

Each item posted to a thread has the following shape:
FieldTypeRequiredDescription
idstringYesServer-generated unique item id.
session_idstringYesSession that owns this item.
revision_idstringYesRevision that owns this item.
aliasstringYesAlias of the thread envelope this item belongs to.
created_atstringYesISO 8601 timestamp stamped by the server on creation.
user_idstringYesId of the user who posted the item.
contentarray of objectYesOrdered list of content blocks. Each block has a type field: "text" or "json".
parent_idstringNoOptional reference to a parent item id (stored only; not enforced by the server).
metadataobjectNoOptional arbitrary JSON for application-level annotation.

​
Content Blocks

Each entry in content is an object with a type discriminator:
typeAdditional fieldDescription
"text"text (string)Plain text content.
"json"json (any)Arbitrary JSON payload.
Items are immutable once posted. There is no per-item update or delete command. To remove all items, delete the envelope — this cascades and removes every item in the thread.

​
Operations

OperationDescription
Post Session Thread ItemAppend an item to the thread.
List Session Thread ItemsPage items, sorted by created_at.
Get Session Thread ItemFetch a single item by id.
All three commands require the alias of the thread envelope. If the envelope does not exist or its value.type is not "thread", the server returns invalid_thread_envelope.

​
Events

After each post_session_thread_item call the server emits a session_thread_item_posted event: 
{
  "type": "session_thread_item_posted",
  "session_object": {
    "alias": "onboarding_thread",
    "item_id": "uuid-of-the-new-item"
  }
}
Listeners can use item_id together with created_since in list_session_thread_items to fetch only new items since the last known position.

​
See also