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

# Upload Session File

Upload bytes to session storage, creating or replacing a `file` session object.

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

<Note>
  This is a binary command: the file bytes are the `application/octet-stream` request body, and the
  JSON command below is serialized onto a single line into the `X-Request-Body` header instead of the
  body. `X-Request-Body` is named in the API's `Access-Control-Allow-Headers`, so a browser client can
  send it.
</Note>

### Request Body

Serialized into `X-Request-Body`, not into the body itself:

| Parameter      | Type    | Required | Description                                                                                                              |
| :------------- | :------ | :------- | :----------------------------------------------------------------------------------------------------------------------- |
| `engine`       | string  | Yes      | Must be `workflow_blobhub`.                                                                                              |
| `command`      | string  | Yes      | Must be `upload_session_file`.                                                                                           |
| `session_id`   | string  | Yes      | The ID of the session.                                                                                                   |
| `alias`        | string  | Yes      | Path-style alias for the object (see grammar note below).                                                                |
| `name`         | string  | Yes      | File name, 1–256 characters.                                                                                             |
| `content_type` | string  | Yes      | MIME type of the file; must match the [content-type allow-list](/blob-types/workflow/session-objects/file/introduction). |
| `size`         | integer | Yes      | Declared size of the bytes, in bytes (0 or more). Must match the octet-stream body's actual length.                      |

The `alias` must conform to the [session-object alias grammar](/blob-types/workflow/session-objects/introduction):
one or more `/`-separated segments of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`, `@`; 1–256 characters total; no
segment may be `.` or `..`. An alias outside the grammar returns `400 invalid_session_object_alias`. A successful
upload fires a `session_object_modified` [session event](/blob-types/workflow/workflows/session-events).

### Response

Unlike `upload_session_object`, this command returns the created object's full envelope, since the
server computes `size` and `sha256` from the bytes it received:

| Parameter | Type   | Description                                     |
| :-------- | :----- | :---------------------------------------------- |
| `object`  | object | The created or replaced file object's envelope. |

### Errors

* `unsupported_file_type` — `content_type` (after dropping parameters and lower-casing) does not match
  any entry in the [content-type allow-list](/blob-types/workflow/session-objects/file/introduction).
* `session_file_too_large` — the uploaded bytes exceed the 4 MiB limit.
* `session_file_size_mismatch` — the declared `size` does not match the number of bytes actually
  received.
* `invalid_file_object` — the alias already names a session object that exists and is not a `file`.

### Example

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST https://api.blobhub.io/v1/revisions/rev_001/data/command \
    -H "X-API-Key: $BLOB_API_KEY" \
    -H "Content-Type: application/octet-stream" \
    -H 'X-Request-Body: {"engine":"workflow_blobhub","command":"upload_session_file","session_id":"sess_001","alias":"report","name":"report.pdf","content_type":"application/pdf","size":154829}' \
    --data-binary @report.pdf
  ```

  ```json Response theme={null}
  {
    "status": "success",
    "object": {
      "revision_id": "rev_001",
      "session_id": "sess_001",
      "alias": "report",
      "updated_at": "2026-07-12T10:00:00.000000Z",
      "value": {
        "type": "file",
        "file": {
          "name": "report.pdf",
          "content_type": "application/pdf",
          "size": 154829,
          "sha256": "bc3863f758932818eedbdaa783c4f7b62e5119c87cbd94725e2ce483c5623fe7"
        }
      }
    }
  }
  ```
</CodeGroup>

### See also

* [File session object](/blob-types/workflow/session-objects/file/introduction) — envelope shape and
  limits.
* [Download Session File](/blob-types/workflow/operations/download-session-file) — read the bytes back.