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