Skip to main content
POST
Prepare Asset Upload
Starts the two-phase private upload: declare the file’s metadata and hash, receive a short-lived signed PUT target. Upload the bytes there, then call finalize. Size limits per kind: IMAGE 25 MB, FILE 100 MB, AUDIO 250 MB, VIDEO 2 GB (confirm live values via capabilities). Canonical documents reference assets by id only — raw storage URLs are rejected at write time. Requirements: instructions:write + workspace EDITOR or OWNER + a verified (claimed) account.

Request

string
required
The owning workspace (assets never cross workspace boundaries).
string
required
Original filename.
string
required
MIME type — also determines the default kind.
number
required
Exact byte size, checked against the per-kind limit.
string
required
Lowercase hex SHA-256 of the file bytes.
string
Override: IMAGE, FILE, AUDIO, or VIDEO.

Response

Returns 201.
object
The PENDING asset record.
object
{url, method: "PUT", headers, expiresAt} — send the raw bytes to url with the given headers before expiresAt.