Skip to content

Upload raw bytes

POST
/storage/objects

Stores the bytes in the request body and returns their SHA-256 hash. To turn them into an asset, call POST /assets with that hash next.

Send the file as the raw body and its media type in X-Content-Type. Any signed-in account can upload; there’s no capability check, and this route doesn’t check the file’s type or size.

The server reads the whole body before it answers, even when it has seen the bytes before, so a repeat upload still sends everything and an interrupted one starts again. The same bytes always give the same hash. If the server already has a record of that hash, it skips writing the bytes and answers deduped: true, without checking that the stored copy is still there or restoring it.

The upload records the bytes as held by your account (the pin_* fields), unless your account already holds them, in which case nothing new is added. The server doesn’t delete stored bytes at the moment, so an upload that never becomes an asset stays stored.

X-Content-Type
string

The file’s media type, such as image/png. It’s recorded with the bytes as sent, without any check; leave it out or empty for application/octet-stream. The record is shared, so a later upload of the same bytes with another type replaces it. The raw download routes don’t send it back.

The file’s bytes. They’re stored exactly as sent, whatever the request’s Content-Type, so don’t wrap them in a form or JSON.

string format: binary

The upload is recorded under its hash.

object
hash
required

The SHA-256 of the bytes, as 64 lowercase hex characters. Send it as file_hash to POST /assets.

string
Example
a1b2c3d4e5f6...0123
size
required

The number of bytes received in this upload.

integer format: int64
content_type
required

The media type this upload recorded, from X-Content-Type.

string
Example
image/jpeg
deduped
required

true if the server already had a record of these bytes and skipped writing them, without checking the stored copy. They were still sent in full.

boolean
pin_subject_type
required

Always user here: the bytes are recorded as held by your account.

string
Example
user
pin_subject_id
required

Your account’s ref, as a string.

string
Example
9

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed