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. Contact our Sales team if you need more than 100 buckets.

The API calls related to buckets are:

Warning: Do not include Protected Health Information (PHI) or Personally Identifiable Information (PII) in bucket names, object/file/folder names, or other metadata. Such metadata is not encrypted in a way that meets Health Insurance Portability and Accountability Act (HIPAA) protection requirements for PHI/PII data and is not generally encrypted in client-side encryption architectures.

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 63 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

You can add key/value pairs as custom information associated with the bucket. 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.

There is no limit on the size or content of the values, other than the overall size limit.

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.