b2_update_bucket
- 11 Sep 2026
- Print
- DarkLight
b2_update_bucket
- Updated on 11 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/b2api/v4/b2_update_bucket
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.
Warning
Do not include Protected Health Information (PHI) or Personally Identifiable Information (PII) in bucket names; object, file, or folder names; or other metadata. This metadata is not encrypted in a way that meets Health Insurance Portability and Accountability Act (HIPAA) protection requirements for PHI/PII data, and it is not generally encrypted in client-side encryption architectures.
Note: Use This API Exclusively for Lifecycle Rule Management
If you use the S3 Compatible API to manage lifecycle rules, do not modify lifecycle rules through other interfaces:
- B2 Web Console: You can view lifecycle rules in the web console, but do not use it to create, update, or delete rules.
- B2 Native API (b2_update_bucket): Do not include the lifecycleRules parameter when calling b2_update_bucket. To update other bucket settings without affecting lifecycle rules, omit the lifecycleRules field entirely—this indicates "no changes" to the existing lifecycle configuration.
Modifying lifecycle rules through the web console or B2 Native API regenerates the rule IDs. If you track lifecycle rules by their ID values or need IDs to remain stable, use only this API to manage lifecycle rules.
API Versions
v2: Consistent file structures (Sept 13, 2018)
Now returns action ("start"), contentLength (0), and contentSha1 ("none").
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)
For information on all API versions, view our API changelog.
Header parameters
Authorization
stringRequired
An account authorization token, obtained from b2_authorize_account.
The token must have the writeBuckets capability.
Body parameters
object
accountId
string
The account that the bucket is in.
ExampleACCOUNT_ID
bucketId
string Required
The unique identifier of the bucket.
Example4a48fe8875c6214145260818
bucketType
string
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.
ExampleallPublic
bucketInfo
object
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.
Example{}
corsRules
Array of object
The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
Example[ { "corsRuleName": "downloadFromAnyOrigin", "allowedOrigins": [ "https" ], "allowedHeaders": [ "range" ], "allowedOperations": [ "b2_download_file_by_id", "b2_download_file_by_name" ], "exposeHeaders": [ "x-bz-content-sha1" ], "maxAgeSeconds": 3600 } ]
object
corsRuleName
string
ExampledownloadFromAnyOrigin
allowedOrigins
Array of string
Example[ "https" ]
string
allowedHeaders
Array of string
Example[ "range" ]
string
allowedOperations
Array of string
Example[ "b2_download_file_by_id", "b2_download_file_by_name" ]
string
exposeHeaders
Array of string
Example[ "x-bz-content-sha1" ]
string
maxAgeSeconds
integer
Example3600
defaultRetention
string
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.
Example
defaultServerSideEncryption
object
The default server-side encryption settings for new files uploaded to this bucket. If this field is omitted, the current setting remains unchanged. If mode is explicitly set to null, the request is accepted and the bucket's effective default is reset to SSE-B2 with AES256. Encryption is not disabled. Explicitly setting or resetting this field requires writeBucketEncryption.
Example{ "mode": null }
mode
string
algorithm
string
fileLockEnabled
boolean
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 fileRetention and legalHold parameters. The original file can then be deleted with b2_delete_file_version.
lifecycleRules
object
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.
Example[ { "daysFromHidingToDeleting": 30, "daysFromUploadingToHiding": null, "fileNamePrefix": "backup/" } ]
daysFromHidingToDeleting
integer
Example30
daysFromUploadingToHiding
string
Example
fileNamePrefix
string
Examplebackup/
replicationConfiguration
object
The configuration to create a Replication Rule. See Cloud Replication Rules. At least one of the asReplicationSource or asReplicationDestination parameters is required, but they can also both be present.
NOTE: The first time that you configure Cloud Replication, complete the following tasks to ensure that you have the correct permission:
- Verify your email address.
- Have a payment history on file or make a payment.
Example{ "asReplicationSource": { "replicationRules": [ { "destinationBucketId": "3f46fe8276c62b414506021y", "fileNamePrefix": "", "includeExistingFiles": false, "isEnabled": true, "priority": 1, "replicationRuleName": "replication-us-east" } ], "sourceApplicationKeyId": "00512f95cf4dcf0000000004z" } }
asReplicationSource
object
replicationRules
Array of object
object
destinationBucketId
string
Example3f46fe8276c62b414506021y
fileNamePrefix
string
Example
includeExistingFiles
boolean
Examplefalse
isEnabled
boolean
Exampletrue
priority
integer
Example1
replicationRuleName
string
Examplereplication-us-east
asReplicationDestination
object
sourceToDestinationKeyMapping
string
Example00512f95cf4dcf0000000004y
ifRevisionIs
integer
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.
Example1
Responses
200
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.
object
accountId
string
The account that the bucket is in.
ExampleACCOUNT_ID
bucketId
The unique identifier of the bucket.
Example4a48fe8875c6214145260818
bucketName
string
The unique name of the bucket
Exampleany-name-you-pick
bucketType
string
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 in the Backblaze web UI.
ExampleallPrivate
bucketInfo
string
The user data stored with this bucket.
Example{}
corsRules
Array of object
The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
Example[ { "corsRuleName": "downloadFromAnyOrigin", "allowedOrigins": [ "https" ], "allowedHeaders": [ "range" ], "allowedOperations": [ "b2_download_file_by_id", "b2_download_file_by_name" ], "exposeHeaders": [ "x-bz-content-sha1" ], "maxAgeSeconds": 3600 } ]
object
corsRuleName
string
ExampledownloadFromAnyOrigin
allowedOrigins
Array of string
Example[ "https" ]
string
allowedHeaders
Array of string
Example[ "range" ]
string
allowedOperations
Array of string
Example[ "b2_download_file_by_id", "b2_download_file_by_name" ]
string
exposeHeaders
Array of string
Example[ "x-bz-content-sha1" ]
string
maxAgeSeconds
integer
Example3600
fileLockConfiguration
object
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.
Example{ "isClientAuthorizedToRead": true, "value": { "defaultRetention": { "mode": null, "period": null }, "isFileLockEnabled": true } }
isClientAuthorizedToRead
boolean
Exampletrue
value
object
defaultRetention
object
mode
string
Examplegovernance
period
object
Example{ "duration": 2, "unit": "years" }
duration
integer
Example2
unit
string
Exampleyears
isFileLockEnabled
boolean
Exampletrue
defaultServerSideEncryption
object
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.
Example{ "isClientAuthorizedToRead": true, "value": { "algorithm": "AES256", "mode": "SSE-B2" } }
isClientAuthorizedToRead
boolean
value
object
algorithm
string
mode
string
lifecycleRules
object
The initial list of lifecycle rules for this bucket. See Lifecycle Rules for an overview and the rule structure.
Example[ { "daysFromHidingToDeleting": 30, "daysFromUploadingToHiding": null, "fileNamePrefix": "backup/" } ]
daysFromHidingToDeleting
integer
Example30
daysFromUploadingToHiding
string
Example
fileNamePrefix
string
Examplebackup/
replicationConfiguration
object
The list of replication rules for this bucket. See Cloud Replication Rules for an overview and the rule structure.
NOTE: The first time that you configure Cloud Replication, complete the following tasks to ensure that you have the correct permission:
- Verify your email address.
- Have a payment history on file or make a payment.
Example{ "isClientAuthorizedToRead": "true,", "value": { "asReplicationDestination": null, "asReplicationSource": { "replicationRules": [ { "destinationBucketId": "3f46fe8276c62b414506021y", "fileNamePrefix": "", "includeExistingFiles": true, "isEnabled": false, "priority": 1, "replicationRuleName": "testRuleName" } ], "sourceApplicationKeyId": "100c9317036ba5b0000000001" } } }
asReplicationSource
object
replicationRules
Array of object
object
destinationBucketId
string
Example3f46fe8276c62b414506021y
fileNamePrefix
string
Example
includeExistingFiles
boolean
Examplefalse
isEnabled
boolean
Exampletrue
priority
integer
Example1
replicationRuleName
string
Examplereplication-us-east
asReplicationDestination
object
sourceToDestinationKeyMapping
string
Example00512f95cf4dcf0000000004y
revision
string
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.
Example2
options
Array of string
When present and set to s3, the bucket can be accessed through the S3 Compatible API.
Example[ "S3" ]
string
Valid values[ "s3" ]
400
| status | code | description |
|---|---|---|
| 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 | 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. |
object
status
integer
The numeric HTTP status code. Always matches the status in the HTTP response.
Example400
code
string
A single-identifier code that identifies the error.
Exampleinvalid_bucket_name
message
string
A human-readable message, in English, saying what went wrong.
Examplebucket name is too long
401
| status | code | description |
|---|---|---|
| 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 | email_not_verified | A valid email address is required to use Cloud Replication. Please verify your email address. Contact customer support if you have questions. |
| 401 | expired_auth_token | The auth token used has expired. Call b2_authorize_account again to get a new one. |
| 401 | no_payment_history | A payment history is required to use Cloud Replication. Please make a payment before configuring Cloud Replication. Contact customer support if you have questions. |
| 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
| status | code | description |
|---|---|---|
| 403 | transaction_cap_exceeded | Transaction cap exceeded. Daily transaction caps apply to non-paying accounts. To view or adjust your caps, sign in to your B2 Cloud Storage account online and select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar. |
409
| status | code | description |
|---|---|---|
| 409 | conflict | The ifRevisionIs test failed. |
Was this article helpful?