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

# Session Objects

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:

| Field         | Type   | Description                                                                   |
| :------------ | :----- | :---------------------------------------------------------------------------- |
| `revision_id` | string | Revision that owns this object.                                               |
| `session_id`  | string | Session that owns this object.                                                |
| `alias`       | string | Path-style name for this object within the session (see Alias grammar below). |
| `updated_at`  | string | ISO 8601 timestamp of the last `upload_session_object` call.                  |
| `value`       | object | The typed payload. Must contain at minimum `"type"` as a discriminator.       |

The `value` object always begins with a `type` string that determines the payload shape:

```json theme={null}
{
  "revision_id": "rev_001",
  "session_id":  "sess_001",
  "alias":       "my_object",
  "updated_at":  "2026-06-06T10:00:00.000000+00:00",
  "value": {
    "type": "...",
    ...
  }
}
```

## Alias grammar (the namespace)

An alias is a **path** — one or more `/`-separated segments — so a session's objects form a filesystem-like
namespace (e.g. `README.md`, `missions/a1b2c3/graph`, `system/config.v2`).

| Rule                     | Value                                                                    |
| :----------------------- | :----------------------------------------------------------------------- |
| Characters (per segment) | `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`, `@`                            |
| Separator                | `/` — one or more segments; no leading/trailing slash, no empty segments |
| Reserved                 | a segment may not be `.` or `..`                                         |
| Length                   | 1–256 characters (whole path)                                            |

Uppercase, dots (including leading dots such as `.gitignore`), and `@` are allowed, so aliases can mirror real
repository paths. The grammar is enforced when an object is **created or overwritten**; reads, deletes, and listing
accept any alias, so objects predating the grammar remain accessible.

This is a session object's own alias, not to be confused with a **session's** or **schedule's** `alias` — the
short, stable name used in place of an id, documented in [Alias Grammar](/blob-types/scheduler/overview#alias-grammar).
The two grammars are deliberately incompatible and never share a value.

[List Session Objects](/blob-types/workflow/operations/list-session-objects) navigates this namespace with `prefix`
(scope a subtree), `delimiter: "/"` (browse one level as folders), and cursor pagination.

## Managing Session Objects

| Operation                                                                          | Description                                                          |
| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------- |
| [Upload Session Object](/blob-types/workflow/operations/upload-session-object)     | Create or replace an object (envelope only).                         |
| [Download Session Object](/blob-types/workflow/operations/download-session-object) | Read back the full envelope.                                         |
| [List Session Objects](/blob-types/workflow/operations/list-session-objects)       | List objects with prefix/delimiter navigation and cursor pagination. |

Uploading an object fires a `session_object_modified`
[session event](/blob-types/workflow/workflows/session-events). Deleting it fires
`session_object_deleted`.

## Types

Some types have additional incremental operations and real-time events beyond the basic
upload/download/list.

| Type       | Description                                                                                           | Details                                                                |
| :--------- | :---------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
| `message`  | A single generative-AI message (role + content + providers + metadata).                               | See [Data Types](/blob-types/workflow/workflows/data-types)            |
| `messages` | An ordered sequence of `message` objects representing a conversation log.                             | See [Data Types](/blob-types/workflow/workflows/data-types)            |
| `thread`   | An append-only stream of structured items. Items live in a separate store with their own API.         | See [thread](/blob-types/workflow/session-objects/thread/introduction) |
| `graph`    | A mutable property graph of vertices and edges. Elements live in a separate store with their own API. | See [graph](/blob-types/workflow/session-objects/graph/introduction)   |

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.