b2_list_buckets
Lists buckets associated with an account, in alphabetical order by bucket name.
When using an authorization token that is restricted to a bucket, you must include the bucketId or bucketName of that bucket in the request, or the request will be denied.
Request
Request HTTP Headers
Authorization
required
An authorization token, obtained from
b2_authorize_account
.
The token must have the listBuckets
capability.
Request HTTP Message Body Parameters
accountId
required
The ID of your account.
bucketId
optional
When bucketId is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this ID.
bucketName
optional
When bucketName is specified, the result will be a list containing just this bucket, if it's present in the account, or no buckets if the account does not have a bucket with this name.
bucketTypes
optional
If present, B2 will use it as a filter for
bucket types returned in the list buckets response. If not present,
only buckets with bucket types "allPublic", "allPrivate" and "snapshot" will be returned.
A special filter value of ["all"] will return all bucket types.
If present, it must be in the form of a json array of
strings containing valid bucket types in quotes and separated by
a comma. Valid bucket types include "allPrivate", "allPublic", "restricted", "snapshot", "shared", and other values added in the future.
A bad request error will be returned if "all" is used with other bucketTypes, bucketTypes is empty, or invalid bucketTypes are requested.
Response
Response HTTP Status 200
Bucket List as a JSON response:
buckets
An array of bucket objects (see below).
Each of the items in the array of buckets:
accountId
The account that the bucket is in.
bucketId
The unique ID of the bucket.
bucketName
The unique name of the bucket
bucketType
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.
bucketInfo
The user data stored with this bucket.
corsRules
The CORS rules for this bucket. See CORS Rules for an overview and the rule structure.
fileLockConfiguration
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.
defaultServerSideEncryption
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.
lifecycleRules
The list of lifecycle rules for this bucket. See Lifecycle Rules for an overview and the rule structure.
replicationConfiguration
The list of replication rules for this bucket. See Cloud Replication Rules for an overview and the rule structure.
revision
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.
options
When present and set to s3
, the bucket can be
accessed through the S3 Compatible API.
Response Errors
When the call is not successful, the body of the response will be a JSON error structure. These are the status and codes that may be returned:
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. |
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. |
API Versions
v2: Remove application key workaround (Sept 13, 2018)
Listing buckets will always return all buckets, unless you ask for just one by specifying
bucketName
or bucketId
. If you ask for all buckets
and your application key is restricted to one bucket, the call is unauthorized.
v1: Workaround for existing applications and application keys (August 9, 2018)
When using an application key that is restricted to a bucket, a request to list all buckets will return just that one bucket instead of returning "unauthorized".
v1: Application keys (July 26, 2018)
New optional bucketName
and bucketId
parameters
to b2_list_buckets provide a way to get
information about just one bucket. This is useful when using an application
key that allows access to only one bucket.
v1: Original release (September 22, 2015)
B2 Cloud Storage was released.Sample Code
Code
ACCOUNT_ID=... #Comes from the b2_authorize_account call
ACCOUNT_AUTHORIZATION_TOKEN=... # Comes from the b2_authorize_account call
API_URL=... # Comes from the b2_authorize_account call
curl \
-H "Authorization: $ACCOUNT_AUTHORIZATION_TOKEN" \
-d "{\"accountId\": \"$ACCOUNT_ID\", \"bucketTypes\": [\"allPrivate\",\"allPublic\"]}" \
"$API_URL/b2api/v2/b2_list_buckets"
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
import java.io.*;
import java.util.*;
import javax.json.*;
import java.net.HttpURLConnection;
import java.net.URL;
String apiUrl = ""; // Provided by b2_authorize_account
String accountId = ""; // Obtained from your B2 account page.
String accountAuthorizationToken = ""; // Provided by b2_authorize_account
HttpURLConnection connection = null;
try {
URL url = new URL(apiUrl + "/b2api/v2/b2_list_buckets");
connection = (HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Authorization", accountAuthorizationToken);
connection.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
connection.setRequestProperty("charset", "utf-8");
connection.setRequestProperty("Content-Length", Integer.toString(postData.length));
connection.setDoOutput(true);
DataOutputStream writer = new DataOutputStream(connection.getOutputStream());
writer.write("{\"accountId\":\"" + accountId + "\", \"bucketTypes\": [\"allPrivate\",\"allPublic\"]}".getBytes(StandardCharsets.UTF_8));
String jsonResponse = myInputStreamReader(connection.getInputStream());
System.out.println(jsonResponse);
} catch (Exception e) {
e.printStackTrace();
} finally {
connection.disconnect();
}
static public String myInputStreamReader(InputStream in) throws IOException {
InputStreamReader reader = new InputStreamReader(in);
StringBuilder sb = new StringBuilder();
int c = reader.read();
while (c != -1) {
sb.append((char)c);
c = reader.read();
}
reader.close();
return sb.toString();
}
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
import json
import urllib2
api_url = "" # Provided by b2_authorize_account
account_id = "" # Obtained from your B2 account page
account_authorization_token = "" # Provided by b2_authorize_account
request = urllib2.Request(
'%s/b2api/v2/b2_list_buckets' % api_url,
json.dumps({ 'accountId' : account_id }),
headers = { 'Authorization': account_authorization_token }
)
response = urllib2.urlopen(request)
response_data = json.loads(response.read())
response.close()
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
import Foundation
let apiUrl = "" // Provided by b2_authorize_account
let accountAuthorizationToken = "" // Provided by b2_authorize_account
let accountId = "" // B2 Cloud Storage Account ID
// Create the request
var request = URLRequest(url: URL(string: "\(apiUrl)/b2api/v2/b2_list_buckets")!)
request.httpMethod = "POST"
request.addValue(accountAuthorizationToken, forHTTPHeaderField: "Authorization")
request.httpBody = "{\"accountId\":\"\(accountId)\"}".data(using: .utf8)
// Create the task
let task = URLSession.shared.dataTask(with: request) { (data, response, error) in
if let data = data {
let json = String(data: data, encoding: .utf8)
print(json!)
}
}
// Start the task
task.resume()
// Swift 4.1 (swiftlang-902.0.48 clang-902.0.37.1) Xcode 9.3.1 (9E501)
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
require 'json'
require 'net/http'
api_url = "" # Provided by b2_authorize_account
account_id = "" # Obtained from your B2 account page
account_authorization_token = "" # Provided by b2_authorize_account
uri = URI("#{api_url}/b2api/v2/b2_list_buckets")
req = Net::HTTP::Post.new(uri)
req.add_field("Authorization","#{account_authorization_token}")
req.body = "{\"accountId\":\"#{account_id}\"}"
http = Net::HTTP.new(req.uri.host, req.uri.port)
http.use_ssl = true
res = http.start {|http| http.request(req)}
case res
when Net::HTTPSuccess then
res.body
when Net::HTTPRedirection then
fetch(res['location'], limit - 1)
else
res.error!
end
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
String apiUrl = "API_URL"; //Provided by b2_authorize_account
String accountAuthorizationToken = "ACCOUNT_AUTHORIZATION_TOKEN"; //Provided by b2_authorize_account
String accountId = "ACCOUNT_ID"; //The unique account ID
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create(apiUrl + "/b2api/v2/b2_list_buckets");
string body = "{\"accountId\":\"" + accountId + "\"}";
var data = Encoding.UTF8.GetBytes(body);
webRequest.Method = "POST";
webRequest.Headers.Add("Authorization", accountAuthorizationToken);
webRequest.ContentType = "application/json; charset=utf-8";
webRequest.ContentLength = data.Length;
using (var stream = webRequest.GetRequestStream())
{
stream.Write(data, 0, data.Length);
stream.Close();
}
WebResponse response = (HttpWebResponse)webRequest.GetResponse();
var responseString = new StreamReader(response.GetResponseStream()).ReadToEnd();
response.Close();
Console.WriteLine(responseString);
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}
Code
$account_id = ""; // Obtained from your B2 account page
$api_url = ""; // From b2_authorize_account call
$auth_token = ""; // From b2_authorize_account call
$session = curl_init($api_url . "/b2api/v2/b2_list_buckets");
// Add post fields
$data = array("accountId" => $account_id);
$post_fields = json_encode($data);
curl_setopt($session, CURLOPT_POSTFIELDS, $post_fields);
// Add headers
$headers = array();
$headers[] = "Authorization: " . $auth_token;
curl_setopt($session, CURLOPT_HTTPHEADER, $headers);
curl_setopt($session, CURLOPT_POST, true); // HTTP POST
curl_setopt($session, CURLOPT_RETURNTRANSFER, true); // Receive server response
$server_output = curl_exec($session); // Let's do this!
curl_close ($session); // Clean up
echo ($server_output); // Tell me about the rabbits, George!
Output
{
"buckets": [
{
"accountId": "12f634bf3cbz",
"bucketId": "4a48fe8875c6214145260818",
"bucketInfo": {},
"bucketName" : "Kitten-Videos",
"bucketType": "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : "AES256",
"mode" : "SSE-B2"
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 3
},
{
"accountId": "12f634bf3cbz",
"bucketId" : "5b232e8875c6214145260818",
"bucketInfo": {},
"bucketName": "Puppy-Videos",
"bucketType": "allPublic",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": null,
"period": null
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [],
"revision": 1
},
{
"accountId": "12f634bf3cbz",
"bucketId": "87ba238875c6214145260818",
"bucketInfo": {},
"bucketName": "Vacation-Pictures",
"bucketType" : "allPrivate",
"corsRules": [],
"defaultServerSideEncryption": {
"isClientAuthorizedToRead" : true,
"value": {
"algorithm" : null,
"mode" : null
}
},
"fileLockConfiguration": {
"isClientAuthorizedToRead": true,
"value": {
"defaultRetention": {
"mode": "governance",
"period": {
"duration": 7,
"unit": "days"
}
},
"isFileLockEnabled": true
}
},
"lifecycleRules": [],
"options": [
"s3"
],
"revision": 5
}
]
}