> ## 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.

# Post Session Thread Item

Append an item to a thread session object.

## **POST** `/revisions/:id/data/command` (Command: `post_session_thread_item`)

### Request Body

| Parameter    | Type            | Required | Description                                                                                                                               |
| :----------- | :-------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------- |
| `engine`     | string          | Yes      | Must be `workflow_blobhub`.                                                                                                               |
| `command`    | string          | Yes      | Must be `post_session_thread_item`.                                                                                                       |
| `session_id` | string          | Yes      | The ID of the session that owns the thread envelope.                                                                                      |
| `alias`      | string          | Yes      | Alias of the thread session object.                                                                                                       |
| `content`    | array of object | Yes      | Array of content blocks. Each block must have a `type` field (`"text"` or `"json"`), plus a `text` string or a `json` value respectively. |
| `parent_id`  | string          | No       | Optional parent item id. Stored only.                                                                                                     |
| `metadata`   | object          | No       | Optional arbitrary JSON.                                                                                                                  |

### Response

Returns the persisted item with server-stamped `id`, `created_at`, `user_id`, and the original/derived
fields.

| Parameter | Type   | Description                                                                                           |
| :-------- | :----- | :---------------------------------------------------------------------------------------------------- |
| `item`    | object | The persisted thread item, including server-stamped `id`, `created_at`, `user_id`, and `revision_id`. |

### Errors

* `invalid_thread_envelope` — the alias does not exist or its `value.type` is not `"thread"`.
* `thread_item_too_large` — the serialized item exceeds the server-side size cap.

### Example

<CodeGroup>
  ```json Request theme={null}
  {
    "engine": "workflow_blobhub",
    "command": "post_session_thread_item",
    "session_id": "sess_001",
    "alias": "onboarding_thread",
    "content": [
      { "type": "text", "text": "Hello, world." }
    ]
  }
  ```

  ```json Response theme={null}
  {
    "item": {
      "id": "itm_01H...",
      "session_id": "sess_001",
      "revision_id": "rev_001",
      "alias": "onboarding_thread",
      "created_at": "2026-05-22T22:00:00.000000+00:00",
      "user_id": "usr_001",
      "content": [
        { "type": "text", "text": "Hello, world." }
      ]
    }
  }
  ```
</CodeGroup>

### See also

* [BlobHub Worker — thread items](/worker/session-agent-harness/thread-items) — how the worker
  structures `content` and `metadata` for agent emissions, and the 380 KB truncation behavior.