Overview
Bucket admin API and file operations.
The storage surface reaches Supabase Storage via the top-level Supabase::Client. It exposes two layers:
- Bucket admin API —
create_bucket,get_bucket,list_buckets,update_bucket,delete_bucket,empty_bucket. Methods called directly onsupabase.storage. - File API —
upload,download,list,move,copy,remove, signed-URL helpers, public-URL helpers. Reached viasupabase.storage.from(bucket_id).
supabase = Supabase.create_client(
supabase_url: ENV.fetch("SUPABASE_URL"),
supabase_key: ENV.fetch("SUPABASE_SERVICE_ROLE_KEY") # bucket admin needs service-role
)
supabase.storage.create_bucket("avatars", public: true)
supabase.storage.list_buckets # => [Supabase::Storage::Types::Bucket(...)]
supabase.storage.from("avatars").upload("ada.png", File.binread("ada.png"))Bucket admin API
| Method | Description |
|---|---|
create_bucket | Create a new bucket. public: true for unauthenticated reads. |
get_bucket | Fetch a single bucket record by id. |
list_buckets | List every bucket the caller can see. |
update_bucket | Patch a bucket's public / file_size_limit / allowed_mime_types. |
empty_bucket | Delete every object inside a bucket without removing the bucket. |
delete_bucket | Delete the bucket itself. Bucket must be empty. |
File API
Scoped to one bucket via supabase.storage.from(bucket_id) (aliases: from_ and bucket).
| Method | Description |
|---|---|
upload | Upload an object. Accepts String bytes, File/IO, or Pathname. |
download | Download object bytes. Optional transform: routes through the image renderer. |
list | List objects under a prefix. Returns the raw response Array<Hash>. |
move | Move (rename) an object inside the same bucket. |
copy | Copy an object inside the same bucket. |
remove | Delete one or more objects by path. |
create_signed_url | Mint a time-limited URL for one object. |
create_signed_urls | Mint signed URLs in bulk for many objects. |
create_signed_upload_url | Mint a pre-signed URL that lets a client upload without your service-role key. |
upload_to_signed_url | Consume a pre-signed URL to upload bytes. Server-side helper. |
get_public_url | Build the public URL for an object in a public: true bucket. |
Bucket type
get_bucket and list_buckets return Supabase::Storage::Types::Bucket structs with these fields:
| Field | Type | Description |
|---|---|---|
id | String | Stable identifier (the slug used in URLs). |
name | String | Display name. Defaults to id on create. |
owner | String | UUID of the user that created the bucket. |
public | Boolean | true if anonymous reads are allowed via the public URL. |
file_size_limit | Integer, nil | Maximum object size in bytes. nil means unbounded. |
allowed_mime_types | Array<String>, nil | Allowlist of content types. nil means any. |
created_at | String | ISO-8601 timestamp. |
updated_at | String | ISO-8601 timestamp. |
type | String, nil | "STANDARD" for object buckets. Present only on newer storage-api versions. |
Authentication
Bucket admin operations require the service-role key — the anon key is rejected by Supabase Storage for every endpoint in this group. Construct the client with the service-role JWT in supabase_key: (or pass a custom Authorization: Bearer ... header) before calling any method on this page.
Service-role key required
Every method on this page requires the service-role JWT. Bucket admin endpoints reject the publishable / anon key with 401 Unauthorized. Keep the service-role key on the server — never ship it to a browser.