Direct Upload (S3 / Spaces)

When ASSET_DIRECT_UPLOAD=true and the project disk is s3, clients can upload straight to the bucket with presigned URLs (and multipart for large files). Classic POST /files remains available.

Requires project token create. Run a queue worker so image finalize jobs complete.

Single-object flow

1. [POST] /files/upload-url — initiate; returns upload URL + asset pending info
2. Client PUTs the file to the signed URL
3. [POST] /files/upload-finalize — finalize; images may enter pending_image_processing

Multipart flow

1. [POST] /files/multipart/initiate
2. [POST] /files/multipart/part-url — per part
3. Client uploads parts
4. [POST] /files/multipart/complete

Threshold/part size: see env.

CORS

Allow your CMS origin and PUT on the bucket. Multipart complete uses S3 ListParts (browsers need not read ETag).

Example (initiate)

curl -X POST "https://your-domain.com/api/files/upload-url" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_PROJECT_TOKEN" \
  -H "project-id: YOUR_PROJECT_UUID" \
  -d '{"filename":"large-video.mp4","content_type":"video/mp4"}'

See Asset Library and classic Upload an Asset.