Buckets

The bucket object

{
  "id": "01m3c081d2wj4g63qcr53pa1yh",
  "name": "invoices",
  "visibility": "public",
  "publicUrl": "https://files.digitospace.com/k3m9q2x7v1c8r4t6w0z5/",
  "bytesStored": 48213,
  "objectCount": 1,
  "webhookUrl": "https://example.com/hooks/storage",
  "createdAt": "2026-09-26T09:00:00Z",
  "updatedAt": "2026-09-26T09:30:00Z"
}

idstring

The bucket’s ID. It never changes, even when you rename the bucket.

namestring

3 to 63 characters: lowercase letters, digits, and single hyphens, starting and ending with a letter or digit. Unique in the project.

visibilitystring

private, where only requests allowed in the project can reach the files, or public, where anyone with a file’s address can open it.

publicUrlstring

Only on public buckets. The start of every file’s public address. See Share files publicly.

bytesStoredinteger

The size of every file in the bucket, in bytes.

objectCountinteger

How many files the bucket holds.

webhookUrlstring

Only when the bucket has a webhook. The address we call when an upload finishes. See Know when an upload finishes.

createdAtstring

When the bucket was created.

updatedAtstring

When the bucket, or a file in it, last changed.

List buckets

Returns the project’s buckets by name, a page at a time. Needs Storage buckets: View.

Create a bucket

{ "name": "invoices" }

Returns 201 with the new bucket. Needs Storage buckets: Create. A name the project already uses gets 409 with bucket_name_taken. A project that already has the most buckets allowed gets 403 with bucket_limit_reached.

Read a bucket

Needs Storage buckets: View.

Change a bucket

Send a new name, a new visibility, or both:

{ "name": "invoices-2026", "visibility": "private" }

Returns the changed bucket. Its files stay where they are. Needs Storage buckets: Edit. Making a bucket public gets 403 with public_buckets_unavailable where public files are not offered.

Delete a bucket

Returns 204. Needs Storage buckets: Delete.

• A bucket with files gets 409 with bucket_not_empty.
• With ?force=true, the bucket and every file in it are deleted. The bucket disappears at once, its files are removed shortly after, and uploads in progress are cancelled. This cannot be undone.

Webhook

Returns the bucket’s webhook, or 404 when it has none. Needs Storage buckets: Edit, because the answer holds the secret.

{ "url": "https://example.com/hooks/storage", "secret": "whsec_…" }

{ "url": "https://example.com/hooks/storage" }

Adds the webhook, or changes its address and keeps its secret. Returns the webhook. Needs Storage buckets: Edit.

urlstringRequired

An https address on a public network, of at most 2,048 characters.

Makes a new secret, used from the next call on, and returns the webhook. Needs Storage buckets: Edit.

Removes the webhook. Calls still waiting to be sent are dropped. Returns 204. Needs Storage buckets: Edit.

Presets

Lists the bucket’s presets, the four built in ones first. Needs Storage buckets: View.

[
  {
    "name": "thumb",
    "width": 200,
    "height": 200,
    "fit": "cover",
    "quality": 80,
    "builtIn": true
  }
]

{ "width": 640, "height": 360, "fit": "cover", "quality": 75 }

Adds or changes a preset, and returns it. Needs Storage buckets: Edit.

namestringRequired

In the path: 1 to 32 lowercase letters, digits, and hyphens, starting with a letter. Not the name of a built in preset.

widthintegerRequired

1 to 4,096 pixels.

heightinteger

1 to 4,096 pixels. Needed with cover.

fitstringRequired

scale-down keeps the shape and never makes an image larger. contain keeps the shape and fits inside the size. cover fills the size and crops what is outside it.

qualityinteger

1 to 100. 80 when you leave it out.

A bucket can hold 20 presets of its own. One more gets preset_limit_reached.

Deletes one of the bucket’s own presets. Returns 204. Needs Storage buckets: Edit.