Skip to main content

Manage storage buckets

Buckets hold your app's files. This page covers creating, updating, checking usage of, and deleting buckets. REST requests go to TARUVI_SITE_URL/api/apps/APP_SLUG/storage/buckets/ with an Authorization: Api-Key TARUVI_API_KEY header.

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

Create a bucket​

In the Console: open your app, select Storage, then Create Bucket. Enter a Bucket Name, choose the Storage Provider, Category, and Visibility, optionally set File Size Limit (MB), and select Create.

With the REST API:

curl -sS -X POST "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"User avatars","visibility":"private","app_category":"assets","file_size_limit":52428800,"allowed_mime_types":["image/*"]}'

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.

curl -sS -X PATCH "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"allowed_mime_types":["image/*","application/pdf"],"file_size_limit":104857600,"max_size_bytes":5368709120}'

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.

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/usage/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

Response body:

{
  "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.

curl -sS -X DELETE "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/BUCKET_SLUG/" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

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

List buckets​

curl -sS "${TARUVI_SITE_URL}/api/apps/APP_SLUG/storage/buckets/?search=avatar&ordering=-created_at" \
  -H "Authorization: Api-Key ${TARUVI_API_KEY}"

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.