Upload Session File - BlobHub

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

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

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.

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.
`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: 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.

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

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

{
  "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"
      }
    }
  }
}

See also

File session object — envelope shape and limits.
Download Session File — read the bytes back.