Upload a raw byte stream

POST

/storage/objects

• Local development behind nginx (port 8088 by default)

Streams the request body to storage, computing sha256 in the same pass. If the resulting hash already exists, the bytes are not re-uploaded — only a new pin is added so the caller’s user keeps the object alive. The response includes a deduped flag so clients can show “already uploaded” UX.

The pin subject for this endpoint is always user:<caller-ref>. Asset entity creation (POST /assets) issues asset:<uuid> pins and removes the user: pin once the entity owns the bytes.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Header Parameters

X-Content-Type

string

Original content type of the upload. Defaults to application/octet-stream when omitted. Recorded as the original variant’s content_type so download responses can set the right Content-Type header.

Request Body ^required

string format: binary

Responses

201

Upload accepted

object

hash

required

Lowercase hex sha256 of the uploaded bytes

string

Example

a1b2c3d4e5f6...0123

size

required

Byte count

integer format: int64

content_type

required

string

Example

image/jpeg

deduped

required

True if the hash was already present on this server and the bytes were NOT re-uploaded to the backend. A new pin was still added for the caller.

boolean

pin_subject_type

required

string

Example

user

pin_subject_id

required

string

Example

9

401

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

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed