Introduction

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:

Field	Type	Description
`attributes`	object	Optional named metadata: `id`, `created_at`, `name`, `description`.
`metadata`	object	Optional 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:

Field	Type	Required	Description
`id`	string	Yes	Server-generated unique item id.
`session_id`	string	Yes	Session that owns this item.
`revision_id`	string	Yes	Revision that owns this item.
`alias`	string	Yes	Alias of the thread envelope this item belongs to.
`created_at`	string	Yes	ISO 8601 timestamp stamped by the server on creation.
`user_id`	string	Yes	Id of the user who posted the item.
`content`	array of object	Yes	Ordered list of content blocks. Each block has a `type` field: `"text"` or `"json"`.
`parent_id`	string	No	Optional reference to a parent item id (stored only; not enforced by the server).
`metadata`	object	No	Optional arbitrary JSON for application-level annotation.

Content Blocks

Each entry in content is an object with a type discriminator:

`type`	Additional field	Description
`"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

Operation	Description
Post Session Thread Item	Append an item to the thread.
List Session Thread Items	Page items, sorted by `created_at`.
Get Session Thread Item	Fetch 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.

Overview

Workflow

Scheduler

ONNX

Envelope

Thread Items

Content Blocks

Operations

Events

See also

​Envelope

​Thread Items

​Content Blocks

​Operations

​Events

​See also

Envelope

Thread Items

Content Blocks

Operations

Events

See also