Upload an object
POST/v1/storage/{project_id}/{bucket}
Multipart upload of a file to a bucket. The object path is not in the URL: it is composed of the path field and the file name of the multipart part.
Headers#
| Header | Required | Value |
|---|---|---|
apikey | yes | Project API key. anon is refused for writes |
Authorization | no | Bearer <JWT>. The user becomes the object's owner |
Content-Type | yes | multipart/form-data (set by the HTTP client) |
Multipart form fields#
| Parameter | Type | Required | Description |
|---|---|---|---|
bucket | string | yes | Bucket name, in the path. The reserved prefix _derivatives is prohibited. |
file | part (file) | yes | Multipart containing the file. Its client file name and content-type are preserved. |
path | part (text) | no | Subfolder in the bucket. The final key is {bucket}/{path}/{filename}. |
upsert | part (text) | no | true or 1 to replace an existing object. Any other value is false. |
meta[key] | part (text) | no | Free metadata attached to the object. |
Limits#
Info
The maximum size is resolved in this order: bucket limit, then project limit, then service configuration. An Content-Length clearly beyond that is rejected even before reading the body. Some extensions are blocked no matter what.
Large files#
Tip
For large files, the API is a three-part multipart: POST …/{bucket}/multipart/init, then PUT …/{bucket}/multipart/part for each part, then POST …/{project_id}/multipart/complete (the latter does not have a bucket segment). DELETE …/{bucket}/multipart aborts the upload. There is no tus API.
Last updated · Apr 15, 2026↗ Edit on GitHub↗ Report a problem