Buckets
Buckets are top-level containers for your files. Create them from the dashboard before uploading.
Creating a bucket
Navigate to your project in the dashboard, select Storage, and click New Bucket. Give the bucket a name — this is what you'll reference in the Flutter SDK.
Buckets must be created before uploading
Calling
Koolbase.storage.upload() with a bucket name that doesn't exist will return a 404 error. Always create buckets from the dashboard first.Naming rules
Lowercase letters, numbers, and hyphens only
Maximum 63 characters
Must be unique within your project
Cannot start or end with a hyphen
Examples: avatars, user-uploads, product-images, documents
Recommended bucket structure
Organise buckets by file type or feature rather than by user. Use the file path within the bucket to scope files per user:
avatars/user_{userId}.jpgProfile photos, one per user
attachments/posts/{postId}/{filename}Post attachments, scoped by post
documents/{userId}/{filename}User documents, scoped by user ID
thumbnails/products/{productId}.jpgProduct images, scoped by product
Deleting a bucket
Buckets can be deleted from the dashboard. Deleting a bucket removes all files within it from R2 and removes all file metadata from the database. This action is permanent and cannot be undone.
Deletion is permanent
Deleting a bucket deletes all files inside it. There is no trash or recovery. Make sure you intend to delete the entire bucket before confirming.