b2_delete_bucket
  • 11 Sep 2026
  • Dark
    Light

b2_delete_bucket

  • Dark
    Light

Article summary

Post
/b2api/v4/b2_delete_bucket

Deletes the bucket specified

Only buckets that contain no version of any files can be deleted.

NOTE:

This API endpoint can be called using a GET request by converting the parameters in the request body to query parameters.


API Versions

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 deleteBuckets capability.

Body parameters
object
accountId
string Required

Your account ID.

ExampleACCOUNT_ID
bucketId
string Required

The ID of the bucket to delete.

Example4a48fe8875c6214145260818
Responses
200

The request succeeded.

Expand All
object
accountId
string

The account that the bucket is in.

ExampleACCOUNT_ID
bucketId
string

The unique identifier of the bucket.

Example3f46fe8276c62b414506021y
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
object

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": null, "mode": null } }
isClientAuthorizedToRead
boolean
value
object
algorithm
string
mode
string
lifecycleRules
object

The initial list (a JSON array) of lifecycle rules for this bucket. See Lifecycle Rules.

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:

  1. Verify your email address.
  2. 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
integer

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.

Example5
options
Array of string

When present, contains a set of strings. Reserved for future use.

Example[ "s3" ]
string
Valid values[ "s3" ]
400
statuscodedescription
400bad_bucket_idThe requested bucket ID does not match an existing bucket.
400bad_requestThe request had the wrong fields or illegal values. The message returned with the error will describe the problem.
400cannot_delete_non_empty_bucketA 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.
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
statuscodedescription
401bad_auth_tokenThe auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
401expired_auth_tokenThe auth token used has expired. Call b2_authorize_account again to get a new one.
401unauthorizedThe 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.

Was this article helpful?