Modifies bucket properties
Update the bucketType, bucket info, lifecycle rules, CORS rules, default server-side encryption settings, or default Object Lock retention settings of an existing bucket. Can be used to allow everyone to download the contents of the bucket without providing any authorization, or to prevent anyone from downloading the contents of the bucket without providing a bucket auth token.
v2: Consistent file structures (Sept 13, 2018)
contentLength (0), and
v1: Application keys (July 26, 2018)
Incompatible change: After calling b2_authorize_account with an application key that does not have the right permissions, this call will return a 401 Unauthorized.
v1: Original release (September 22, 2015)
This API endpoint can be called using a
GET request by converting the parameters in the request body to query parameters.
An account authorization token, obtained from b2_authorize_account.
The token must have the
The account that the bucket is in.
The unique ID of the bucket.
One of: "allPublic", "allPrivate". "allPublic" means that anybody can download the files is the bucket; "allPrivate" means that you need an authorization token to download them.
If not specified, the setting will remain unchanged.
User-defined information to be stored with the bucket: a JSON object mapping names to values. See Buckets.
If specified, the existing bucket info will be replaced with the new info. If not specified, the setting will remain unchanged.
Cache-Control policies can be set here on a global level for all the files in the bucket.
The list of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
If specified, the existing CORS rules will be replaced with this new list. If not specified, the setting will remain unchanged.
The default Object Lock retention settings for this bucket. See Object Lock for an overview and the parameter structure.
If specified, the existing default bucket retention settings will be replaced with the new settings. If not specified, the setting will remain unchanged. Setting the value requires the
writeBucketRetentions capability and that the bucket is Object Lock-enabled.
The default server-side encryption settings for this bucket. See 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 an overview and the parameter structure. If specified, the existing default bucket encryption settings will be replaced with the new settings. If not specified, the setting will remain unchanged. Setting the value requires the
If present, the Boolean value specifies whether the bucket has Object Lock enabled. Once Object Lock is enabled on a bucket, it cannot be disabled.
A value of
true will be accepted if you have writeBucketRetentions capability. But you cannot enable Object Lock on a restricted bucket (e.g. share buckets, snapshot) or on a bucket that contains source replication configuration.
A value of false will only be accepted if the bucket does not have Object Lock enabled.
After enabling Object Lock on a bucket containing files with metadata over the lower 2,048 byte limit, API requests to b2_update_file_retention and b2_update_file_legal_hold will be rejected. This is because setting file retention or legal hold on a file adds additional headers when the file is downloaded, for example, with b2_download_file_by_name. In such cases, you can use b2_copy_file with a
REPLACE metadataDirective to copy the file, give it less metadata, and also specify the
legalHold parameters. The original file can then be deleted with b2_delete_file_version.
The list of lifecycle rules for this bucket. Structure defined below. See Lifecycle Rules for an overview and the rule structure.
If specified, the existing lifecycle rules will be replaced with this new list. If not specified, the setting will remain unchanged.
The list of replication rules for this bucket. See Cloud Replication Rules.
When set, the update will only happen if the revision number stored in the B2 service matches the one passed in. This can be used to avoid having simultaneous updates make conflicting changes.
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.
The account that the bucket is in.
The unique ID of the bucket.
The unique name of the bucket
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 initial 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.|
|400||file_lock_conflict||This operation is not allowed because Object Lock is enabled on the bucket.|
|400||restricted_bucket_conflict||This operation is not allowed because the bucket is restricted.|
|400||source_replication_conflict||This operation is not allowed because source replication configuration is present on the bucket.|
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.|