The storage for your account is grouped into buckets. Each bucket is a container that holds files. You can think of buckets as the top-level folders in your B2 Cloud Storage account. There is no limit to the number of files in a bucket, but there is a limit of 100 buckets per account.

The API calls related to buckets are:

Bucket Names

When you create a bucket, you get to pick the name for the bucket. The name you pick must be a unique name that has not been used before, by you or by anybody else. In other words - a bucket's name is globally unique.

Bucket names can consist of upper-case letters, lower-case letters, numbers, and "-". No other characters are allowed. Even though your bucket can have upper-case letters, bucket names are case insensitive. A bucket name must be at least 6 characters long, and can be at most 50 characters long. These are all allowed bucket names: myBucket, backblaze-images, and bucket-74358734. Bucket names that start with "b2-" are reserved for Backblaze use.

Access Controls

Access controls are simple. Uploads into a bucket always require authorization. Listing files in a bucket always requires authorization, and deleting files always requires authorization. For downloading files, though, you have the option of requiring authorization, or making all of the files in a bucket the files visible to the public.

The bucketType parameter on a bucket sets the access permissions. Setting it to allPrivate means that every download requires an authorization token. Setting it to allPublic means that everybody is allowed to download the files in the bucket.

Note that when a bucket is allPublic, anybody can download the files, but the downloads will still be charged against your account. Each day, anything beyond the 1GB of downloads you get for free will be charged to your account.

Bucket Info

Each bucket has information associated with it. Your custom file information can be up to 10 key/value pairs. Each key is a UTF-8 string up to 50 bytes long, and can contain letters, numbers, and the following list of special characters: "-", "_", ".", "`", "~", "!", "#", "$", "%", "^", "&", "*", "'", "|", "+". Each key is converted to lowercase. Names that begin with "b2-" are reserved. There is an overall limit of 10,000 bytes for all of the values.

You can store bucket info when you create a bucket with b2_create_bucket, and then update the info later with b2_update_bucket.

For names that don't start with "b2-", there is no limit on the size or content of the values, other than the overall size limit.

Names that start with "b2-" must be in the list of defined "b2-" names and their values must be valid. B2 rejects any bucket create or update requests with an unexpected "b2-" info name. B2 also rejects any bucket create or update request with a "b2-" bucket info name whose value doesn't meet the format specified for that name. There are not any defined "b2-" names yet.

This is also where you can set the Cache-Control policy for buckets. For example, if you wanted the client to cache files for 5 minutes, you would add a name/value pair such as "Cache-Control" : "max-age=600"; from then on, when any files from this bucket are downloaded, the response would contain the corresponding header. By default, if no Cache-Control policy is set, all files downloaded from buckets created before September 8, 2021 have a Cache-Control header value of "max-age=0, no-cache, no-store". All buckets created on or after September 8, 2021 include no Cache-Control header by default with file downloads.

Lifecycle Rules

Each bucket has a set of lifecycle rules that instruct B2 to hide or delete old versions of files.