Uploads

Start an upload, send the file with its link, then finish or cancel the upload.

Start an upload

POST/v1/projects/{project}/buckets/{bucket}/uploads

Needs Storage files: Upload.

keystringRequired: Where to store the file. See Choose keys.
sizeintegerRequired: The file’s size in bytes. A larger file is refused when you finish.
contentTypestring: The file’s media type, such as image/png. application/octet-stream when empty.
sha256string: The file’s SHA-256 digest as 64 hexadecimal characters. The link then refuses any other bytes.

Returns 201:

{
  "id": "01m3c3zq7rj2ab0x5w8k1v9yag",
  "bucket": "01m3c081d2wj4g63qcr53pa1yh",
  "key": "2026/0001.pdf",
  "size": 48213,
  "contentType": "application/pdf",
  "expiresAt": "2026-09-26T11:00:00Z",
  "upload": {
    "method": "PUT",
    "url": "https://…",
    "headers": { "Content-Type": "application/pdf" },
    "expiresAt": "2026-09-26T10:15:00Z"
  }
}

Send the file’s bytes to upload.url with upload.method and every header in upload.headers, within 15 minutes.
expiresAt is when the upload is cancelled if you have not finished it: 1 hour.
A project without room gets 403 with storage_quota_reached. A project with too many uploads in progress gets 403 with upload_limit_reached.

Finish an upload

POST/v1/projects/{project}/buckets/{bucket}/uploads/{upload}/complete

Returns the stored file. Needs Storage files: Upload.

Code	Status	When
`upload_incomplete`	409	The file has not arrived yet. Send it, then finish again
`upload_size_mismatch`	409	The file is larger than declared, or its digest does not match. The upload is cancelled
`upload_finished`	409	The upload expired, was cancelled or refused, or its file was since replaced
`storage_quota_reached`	403	The file no longer fits in the project’s storage

Finishing an upload that already finished answers with the same file.

Cancel an upload

DELETE/v1/projects/{project}/buckets/{bucket}/uploads/{upload}

Returns 204, and the file sent to it, if any, is removed. Needs Storage files: Upload. Cancelling an upload that already stopped also returns 204.

Last updated 30 September 2026