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.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Header Parameters
Section titled “Header Parameters ”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.
Request Body required
Section titled “Request Body required ”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.
Responses
Section titled “ Responses ”The upload is recorded under its hash.
object
The SHA-256 of the bytes, as 64 lowercase hex characters. Send it as file_hash to POST /assets.
Example
a1b2c3d4e5f6...0123The number of bytes received in this upload.
The media type this upload recorded, from X-Content-Type.
Example
image/jpegtrue 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.
Always user here: the bytes are recorded as held by your account.
Example
userYour account’s ref, as a string.
Example
9Authentication required, missing, or invalid
object
Human-readable error summary
Example
the request could not be completedExample
{ "error": "authentication required: sign in and retry with a valid session or API token"}Unexpected server error
object
Human-readable error summary
Example
the request could not be completed