> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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"`:

```json theme={null}
{
  "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](/blob-types/workflow/operations/post-session-thread-item)   | Append an item to the thread.       |
| [List Session Thread Items](/blob-types/workflow/operations/list-session-thread-items) | Page items, sorted by `created_at`. |
| [Get Session Thread Item](/blob-types/workflow/operations/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`](/blob-types/workflow/workflows/session-events) event:

```json theme={null}
{
  "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

* [Session Objects — Introduction](/blob-types/workflow/session-objects/introduction) — envelope
  mechanics and the full list of session object types.
* [Session Events](/blob-types/workflow/workflows/session-events) — full event reference.