This API request is now being described as a
GET request and not a
POST request, as was the case in previous versions of our documentation.
We made this update because we believe that an API call that retrieves data and does not alter state is more accurately represented as a GET request.
You may still make a POST request to this endpoint by simply submitting a JSON-formatted request body containing the parameters, with
Content-Type set to
Lists buckets alphabetically by name
When using an authorization token that is restricted to a bucket, you must include the
bucketName of that bucket in the request, or the request will be denied.
v2: Remove application key workaround (Sept 13, 2018)
Listing buckets will always return all buckets, unless you ask for just one by specifying
bucketId. If you ask for all buckets and your application key is restricted to one bucket, the call is unauthorized.
v1: Workaround for existing applications and application keys (August 9, 2018)
When using an application key that is restricted to a bucket, a request to list all buckets will return just that one bucket instead of returning "unauthorized".
v1: Application keys (July 26, 2018)
bucketId parameters to b2_list_buckets provide a way to get information about just one bucket. This is useful when using an application key that allows access to only one bucket.
v1: Original release (September 22, 2015)
B2 Cloud Storage was released.
An account authorization token, obtained from b2_authorize_account.
The token must have the
The ID of your account.
bucketId is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this ID.
bucketName is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this name.
If present, B2 will use it as a filter for bucket types returned in the list buckets response. If not present, only buckets with bucket types "allPublic", "allPrivate" and "snapshot" will be returned. A special filter value of ["all"] will return all bucket types.
If present, it must be in the form of a json array of strings containing valid bucket types in quotes and separated by a comma. Valid bucket types include "allPrivate", "allPublic", "restricted", "snapshot", "shared", and other values added in the future.
A bad request error will be returned if "all" is used with other
bucketTypes is empty, or invalid
bucketTypes are requested.
The request succeeded.
The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.
An array of bucket objects.
The account that the bucket is in.
The unique ID of the bucket.
The unique name of the bucket
One of: allPublic, allPrivate, restricted, snapshot, shared, or other values added in the future. allPublic means that anybody can download the files is the bucket; allPrivate means that you need an authorization token to download them; snapshot means that it's a private bucket containing snapshots created on the B2 web site.
The user data stored with this bucket.
The CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
The Object Lock configuration for this bucket. This field is filtered based on application key capabilities;
readBucketRetentions capability is required to access the value. See Object Lock for more details on response structure.
The default bucket Server-Side Encryption settings for new files uploaded to this bucket. This field is filtered based on application key capabilities; readBucketEncryption capability is required to access the value. See Server-Side Encryption for more details on response structure.
The list of lifecycle rules for this bucket. See Lifecycle Rules for an overview and the rule structure.
The list of replication rules for this bucket. See Cloud Replication Rules for an overview and the rule structure.
A counter that is updated every time the bucket is modified, and can be used with the ifRevisionIs parameter to b2_update_bucket to prevent colliding, simultaneous updates.
When present and set to s3, the bucket can be accessed through the S3 Compatible API.
|400||bad_bucket_id||The requested bucket ID does not match an existing bucket.|
|400||bad_request||The request had the wrong fields or illegal values. The message returned with the error will describe the problem.|
|400||cannot_delete_non_empty_bucket||A bucket must be empty before it can be deleted. To delete this bucket, first remove all of the files in the bucket, then try the delete operation again.|
The numeric HTTP status code. Always matches the status in the HTTP response.
A single-identifier code that identifies the error.
A human-readable message, in English, saying what went wrong.
|401||bad_auth_token||The auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.|
|401||expired_auth_token||The auth token used has expired. Call b2_authorize_account again to get a new one.|
|401||unauthorized||The auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account.|
|403||transaction_cap_exceeded||Transaction cap exceeded. To increase your cap, sign in to your B2 Cloud Storage account online. Then select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar.|