Skip to main content

Manage storage buckets

Buckets hold your app's files. This page covers creating, updating, checking usage of, and deleting buckets. Choose an interface below. REST examples use a server-side API key; keep it out of browser code.

Managing buckets requires an organization owner or admin, or another cloud user with access to the site.

Use the synchronous Python client for the Python examples. Replace BUCKET_SLUG with your bucket slug.

Create a bucket#

client.storage.create_bucket(
    "User avatars",
    visibility="private",
    app_category="assets",
    file_size_limit=52428800,
    allowed_mime_types=["image/*"],
)

The method creates an S3 bucket and returns its details directly.

Response body includes the derived slug, the bucket uuid, and empty usage and quota_status blocks. app_category is required and sets the bucket's starting access policy: assets lets signed-in users read, and attachments lets them read, upload, and update. See Security and limits.

To back a bucket with SharePoint instead of S3, set "storage_provider": "sharepoint" at create time. The provider can't change after creation. SharePoint must be enabled for your site — see Providers, and Troubleshooting if creation fails with sharepoint_site_not_ready.

Update a bucket#

PATCH accepts partial updates to the mutable fields — name, visibility, file_size_limit, allowed_mime_types, tags, max_size_bytes, and max_objects. slug, storage_provider, and app_category can't be changed after creation.

client.storage.update_bucket(
    "BUCKET_SLUG",
    allowed_mime_types=["image/*", "application/pdf"],
    file_size_limit=104857600,
    max_size_bytes=5368709120,
)

The method returns the updated bucket.

PUT isn't supported for buckets; use PATCH. Trying to change storage_provider on a PATCH returns 400 Bad Request with "Bucket storage_provider is immutable after creation.".

Check bucket usage#

Usage is recalculated periodically, not on every upload.

client.storage.get_bucket("BUCKET_SLUG")

Bucket details include usage and quota_status. Their freshness field is usage.last_updated; the REST usage endpoint below uses usage.calculated_at.

REST usage response body:

{
  "status": "success",
  "message": "…",
  "data": {
    "bucket": {"id": 1, "name": "User avatars", "slug": "user-avatars", "has_quota": true},
    "quota":  {"max_size_bytes": 5368709120, "max_size_mb": 5120, "max_objects": null},
    "usage":  {"total_size": 12582912, "total_objects": 17, "size_mb": 12.0, "size_gb": 0.01, "calculated_at": "2026-09-01T00:00:00Z"},
    "exceeded":     {"size": false, "objects": false, "any": false},
    "percent_used": {"size": 0.23, "objects": null},
    "overage":      {"size_bytes": 0, "size_mb": 0, "objects": 0}
  }
}

calculated_at shows when usage was last recalculated. Uploads made after that time appear after the next recalculation.

max_size_bytes and max_objects are optional. When neither is set, has_quota is false and quota_status is null on bucket detail responses. When max_size_bytes is set, it must be at least file_size_limit; otherwise the request is rejected with 400.

Delete a bucket#

Bucket delete is permanent

Deleting a bucket removes every file in it and its access policy. It can't be undone — confirm the bucket slug before you send the request.

client.storage.delete_bucket("BUCKET_SLUG")

The method returns None after the request succeeds.

After delete, reading the same bucket should return not found.

List buckets#

client.storage.list_buckets(search="avatar", ordering="-created_at")

list_buckets returns the bucket list directly. Use page and page_size to select a page.

Filter parameters:

ParameterBehavior
searchCase-insensitive match on name or slug.
orderingcreated_at or updated_at, with optional - prefix.
visibilityExact match — private or public.
app_categoryExact match — assets or attachments.
tagsComma-separated tag slugs. Matches any (OR). Distinct results.