Storage
Upload, serve, and manage files from Flutter. Backed by Cloudflare R2 with direct device-to-cloud uploads via presigned URLs.
How it works
Koolbase Storage uses a three-step upload flow to avoid routing file data through the API server. Instead, your app uploads directly to Cloudflare R2 using a short-lived presigned URL — fast, efficient, and scalable.
1
Request a presigned URL
Your app asks the Koolbase API for a one-time upload URL for a specific bucket and path.
2
Upload directly to R2
Your app sends the file directly to Cloudflare R2 using the presigned URL. The API server is not involved in the upload.
3
Confirm the upload
Your app tells the Koolbase API the upload is complete. File metadata is recorded in the database.
The Flutter SDK handles all three steps
When you call
Koolbase.storage.upload(), the SDK handles the presigned URL request, the R2 upload, and the confirmation automatically. You don't need to manage the three steps manually.Key concepts
BucketA named container for files — like a folder at the top level. Created from the dashboard.PathThe location of a file within a bucket. e.g. avatars/user_123.jpgPresigned URLA short-lived, single-use URL that grants temporary write access to a specific R2 path.Download URLA URL to retrieve a file. Can be public (direct R2 link) or time-limited.MetadataFile info (name, size, content type, path) stored in PostgreSQL after a confirmed upload.In this section
Storage vs Database
Use Storage for binary files — images, videos, documents, audio. Use the Database for structured JSON data — profiles, posts, settings. Do not try to store file contents as base64 in database records.