> ## 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 `file` session object is a named binary or text file: an envelope holding metadata, with the bytes
stored separately. It can only be created by `upload_session_file` — `upload_session_object` refuses a
`value.type` of `"file"`.

## Envelope

`upload_session_file` writes the bytes and the envelope together in one call. The stored `value` looks
like:

```json theme={null}
{
  "type": "file",
  "file": {
    "name": "report.pdf",
    "content_type": "application/pdf",
    "size": 154829,
    "sha256": "bc3863f758932818eedbdaa783c4f7b62e5119c87cbd94725e2ce483c5623fe7"
  }
}
```

| Field | Type | Description |
| :- | :- | :- |
| `name` | string | File name, 1–256 characters. |
| `content_type` | string | Normalized MIME type (parameters dropped, lower-cased). |
| `size` | integer | Size of the stored bytes. |
| `sha256` | string | SHA-256 digest of the stored bytes, as lowercase hex. |

The bytes themselves live at a side storage prefix next to the object store, not inside it — they are
never listed as a second object by [List Session Objects](/blob-types/workflow/operations/list-session-objects),
and only `download_session_file` reads them back. Deleting the object with `delete_session_object`
cascades and removes the bytes with it; deleting the session purges every file's bytes along with
everything else in it.

## Limits

| Limit | Value |
| :- | :- |
| Max file size | 4 MiB (4,194,304 bytes) per file — [`workflow.session_file_bytes`](/general/limits#workflow). |
| Allowed content types | `image/png`, `image/jpeg`, `image/gif`, `image/webp`, `application/pdf`, `application/json`, `text/*`, `audio/*`, `video/*`, `application/vnd.openxmlformats-officedocument.*` — a trailing `*` matches its whole family by prefix. |

<Note>
  `upload_session_object` refuses a `value.type` of `"file"` — a file object can only be created with
  `upload_session_file`, so a `file` envelope never exists without bytes behind it.
</Note>

## Operations

| Operation | Description |
| :- | :- |
| [Upload Session File](/blob-types/workflow/operations/upload-session-file) | Upload bytes, creating or replacing the file object. |
| [Download Session File](/blob-types/workflow/operations/download-session-file) | Download the bytes and the envelope together. |

## See also

* [Thread — Introduction](/blob-types/workflow/session-objects/thread/introduction) — a thread item's
  `file` content block references a `file` object by alias.
* [Session Objects — Introduction](/blob-types/workflow/session-objects/introduction) — envelope
  mechanics and the full list of session object types.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.