b2_create_bucket

Print
Dark
Light

b2_create_bucket

Print
Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

Post

/b2api/v2/b2_create_bucket

Creates a new bucket

A bucket belongs to the account used to create it.

Buckets can be named. The name must be globally unique. No account can use a bucket with the same name. Buckets are assigned a unique bucketId which is used when uploading, downloading, or deleting files. There is a limit of 100 buckets per account. Contact our Sales team if you need more than 100 buckets.

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.

PLEASE NOTE:

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

Header parameters

Authorization

stringRequired

An account authorization token, obtained from b2_authorize_account.
The token must have the writeBuckets capability.

Body parameters

Expand All

object

accountId

string Required

Your account ID.

ExampleSOURCE_FILE_ID

bucketName

string Required

The name to give the new bucket.

Bucket names must be a minimum of 6 and a maximum of 63 characters long, and must be globally unique, two different B2 accounts cannot have buckets with the same name. Bucket names can consist of letters, digits, and "-". Bucket names cannot start with "b2-", these are reserved for internal Backblaze use.

ExampleBUCKET_ID

bucketType

string Required

Either "allPublic", meaning that files in this bucket can be downloaded by anybody, or "allPrivate", meaning that you need a bucket authorization token to download the files.

ExampleallPublic

bucketInfo

string

User-defined information to be stored with the bucket as a JSON object mapping names to values. See Buckets. Cache-Control policies can be set here on a global level for all the files in the bucket.

Examplebytes=0-4999999

corsRules

string

The initial list (a JSON array) of CORS rules for this bucket. See CORS Rules for an overview and the rule structure.

ExampleSOURCE_FILE_DATA_ACCESS_PARAMETERS

fileLockEnabled

boolean

If present, the boolean value specifies whether bucket is Object Lock-enabled. The default value is false. Setting the value to true requires the writeBucketRetentions capability.

lifecycleRules

object

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

daysFromHidingToDeleting

integer

Example30

daysFromUploadingToHiding

string

Example

fileNamePrefix

string

Examplebackup/

replicationConfiguration

string

The configuration to create a Replication Rule. See Cloud Replication Rules.

Example

defaultServerSideEncryption

object

The default server-side encryption settings for this bucket. See Server-Side Encryption for an overview and the parameter structure.

Setting the value requires the writeBucketEncryption application key capability.

mode

string

algorithm

string

Responses

200

The request succeeded.

Array of object

object

accountId

string

The account that the bucket is in.

Example12f634bf3cbz

bucketId

integer

The unique ID 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 on the B2 web site.

ExampleallPrivate

bucketInfo

string

The user data stored with this bucket.

Exampled131dd02c5e6eec4

corsRules

string

The CORS rules for this bucket. See CORS Rules for an overview and the rule structure.

ExampleBUCKET_ID

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.

isClientAuthorizedToRead

boolean

ExampleTrue

value

object

defaultRentention

object

mode

string

Examplegovernance

period

object

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.

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 for an overview and the rule structure.

daysFromHidingToDeleting

integer

Example30

daysFromUploadingToHiding

string

Example

fileNamePrefix

string

Examplebackup/

replicationConfiguration

integer

The list of replication rules for this bucket. See Cloud Replication Rules for an overview and the rule structure.

Example1559585618236

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.

Example1559585618236

options

Array of string

When present and set to s3, the bucket can be accessed through the S3 Compatible API.

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	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	too_many_buckets	The account is already at the maximum bucket count.
400	duplicate_bucket_name	Bucket name is already in use.

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

status	code	description
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.

What's Next

b2_create_key