b2_create_bucket
- Print
- DarkLight
b2_create_bucket
- Print
- DarkLight
Article Summary
Share feedback
Thanks for sharing your feedback!
Post
/b2api/v3/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
object
accountId
string Required
Your account ID.
ExampleYOUR_ACCOUNT_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_NAME
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
object
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.
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
string
Example[ "https" ]
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
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.
ExampleTrue
lifecycleRules
object
The initial list (a JSON array) of lifecycle rules for this bucket. Structure defined below. See Lifecycle Rules.
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.
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
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.
Example{ "mode": "SSE-B2", "algorithm": "AES256" }
mode
string
algorithm
string
Responses
200
The request succeeded.
object
accountId
string
The account that the bucket is in.
ExampleYOUR_ACCOUNT_ID
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 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
defaultRentention
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 (a JSON array) 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.
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.
Example1559585618236
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 | 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. |
503
| status | code | description |
|---|---|---|
| 503 | service_unavailable | The service is currently unavailable. Please retry with exponential backoff if needed. |
Was this article helpful?