Organise buckets and files

Name a bucket

Bucket names are 3 to 63 characters: lowercase letters, digits, and single hyphens, starting and ending with a letter or digit. They are unique in a project. You can use a bucket’s name or its ID in every path.

Rename a bucket without moving its files:

curl -X PATCH "$STORAGE_URL/buckets/invoices" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "invoices-2026"}'

Choose keys

A key is up to 1,024 bytes of UTF-8, such as customers/4471/avatar.png.

• Use / to group files into folders.
• A key cannot start or end with /, hold //, or have a folder named . or ...
• Control characters are not allowed.

Create folders

A folder appears on its own when you upload a file into it, such as 2026/0001.pdf creating 2026/. To show an empty folder before it holds files, create it:

curl -X POST "$STORAGE_URL/buckets/invoices/folders" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "2026"}'

An empty folder can be deleted. A folder that still holds files cannot, so delete its files first.

List files and folders

List every file in the bucket, in key order:

curl "$STORAGE_URL/buckets/invoices/objects" \
  -H "Authorization: Bearer $STORAGE_API_KEY"

List one folder at a time with delimiter=/. Folders come back as entries with "type": "folder", and files with "type": "file":

curl "$STORAGE_URL/buckets/invoices/objects?prefix=2026/&delimiter=/" \
  -H "Authorization: Bearer $STORAGE_API_KEY"

Lists come in pages of 100, or up to 1,000 with limit. See Paging.

Copy a file

Copy a file to another key, in the same bucket or another one in the project:

curl -X POST "$STORAGE_URL/buckets/invoices/copies" \
  -H "Authorization: Bearer $STORAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key": "2026/0001.pdf", "toBucket": "archive", "toKey": "2026/0001.pdf"}'

The copy counts towards the project’s storage like any other file.

Delete files and buckets

Delete a file. This cannot be undone:

curl -X DELETE "$STORAGE_URL/buckets/invoices/objects/2026/0001.pdf" \
  -H "Authorization: Bearer $STORAGE_API_KEY"

A bucket must be empty to be deleted, or you get bucket_not_empty. To delete a bucket and every file in it, add force=true. The bucket disappears at once, and its files are removed shortly after:

curl -X DELETE "$STORAGE_URL/buckets/invoices?force=true" \
  -H "Authorization: Bearer $STORAGE_API_KEY"