v1

latestOpenAPI 3.1.02026-07-2665164286.3 KB

Assets

Create Asset Upload

Begin a direct-to-S3 upload. Returns an asset_id and a presigned upload_url; PUT the file bytes to upload_url, then call POST /v3/assets/{asset_id}/complete. Unlike POST /v3/assets (which proxies the bytes), this never sends the file through the API.

post/v3/assets/direct-uploads

Headers

Idempotency-Keystring

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Request body

filenamestring required

Original filename for reference/metadata. The stored object's extension is derived from content_type.

content_typestring required

Declared MIME type (e.g. 'video/mp4', 'image/png', 'audio/mpeg', 'application/pdf', 'application/zip'). Verified against the stored bytes at completion.

size_bytesinteger required

Exact byte size of the file. Signed into the upload URL so it cannot be exceeded.

checksum_sha256string nullable

Optional SHA256 of the file as hex. When provided, S3 enforces it on upload.

Response

Successful response