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

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", "snapshot", 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", "snapshot", 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.

lifecycleRules

The list of lifecycle rules for this bucket.

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.

Response Errors

Unable to return Bucket List. If possible the server will return a JSON error structure. Errors include:

status

code

message

400

bad_request

Account <accountId> does not exist

400

bad_request

bucketTypes cannot be empty

400

bad_request

"all" cannot be requested with other bucket types

400

bad_request

Invalid bucketTypes requested

400

bad_request

No Authorization header

401

unauthorized

Not authorized

Sample Code

Code

ACCOUNT_ID=... # Comes from your account page on the Backblaze web site
ACCOUNT_AUTHORIZATION_TOKEN=... # Comes from the b2_authorize_account call
curl \
    -H 'Authorization: $ACCOUNT_AUTHORIZATION_TOKEN' \
    -d '{"accountId": "$ACCOUNT_ID", "bucketTypes": ["allPrivate","allPublic"]}' \
    "https://apiNNN.backblazeb2.com/b2api/v1/b2_list_buckets"

Output

{
    "buckets": [
    {
        "accountId": "30f20426f0b1",
        "bucketId": "4a48fe8875c6214145260818",
        "bucketInfo": {},
        "bucketName" : "Kitten-Videos",
        "bucketType": "allPrivate",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId" : "5b232e8875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Puppy-Videos",
        "bucketType": "allPublic",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId": "87ba238875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Vacation-Pictures",
        "bucketType" : "allPrivate",
        "lifecycleRules": []
    } ]
}

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/v1/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": "30f20426f0b1",
        "bucketId": "4a48fe8875c6214145260818",
        "bucketInfo": {},
        "bucketName" : "Kitten-Videos",
        "bucketType": "allPrivate",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId" : "5b232e8875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Puppy-Videos",
        "bucketType": "allPublic",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId": "87ba238875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Vacation-Pictures",
        "bucketType" : "allPrivate",
        "lifecycleRules": []
    } ]
}

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/v1/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": "30f20426f0b1",
            "bucketId": "4a48fe8875c6214145260818",
            "bucketInfo": {},
            "bucketName" : "Kitten-Videos",
            "bucketType": "allPrivate",
            "lifecycleRules": []
        },
        {
            "accountId": "30f20426f0b1",
            "bucketId" : "5b232e8875c6214145260818",
            "bucketInfo": {},
            "bucketName": "Puppy-Videos",
            "bucketType": "allPublic",
            "lifecycleRules": []
        },
        {
            "accountId": "30f20426f0b1",
            "bucketId": "87ba238875c6214145260818",
            "bucketInfo": {},
            "bucketName": "Vacation-Pictures",
            "bucketType" : "allPrivate",
            "lifecycleRules": []
        } ]
}

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/v1/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": "30f20426f0b1",
        "bucketId": "4a48fe8875c6214145260818",
        "bucketInfo": {},
        "bucketName" : "Kitten-Videos",
        "bucketType": "allPrivate",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId" : "5b232e8875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Puppy-Videos",
        "bucketType": "allPublic",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId": "87ba238875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Vacation-Pictures",
        "bucketType" : "allPrivate",
        "lifecycleRules": []
    } ]
}

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/v1/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": "30f20426f0b1",
        "bucketId": "4a48fe8875c6214145260818",
        "bucketInfo": {},
        "bucketName" : "Kitten-Videos",
        "bucketType": "allPrivate",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId" : "5b232e8875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Puppy-Videos",
        "bucketType": "allPublic",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId": "87ba238875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Vacation-Pictures",
        "bucketType" : "allPrivate",
        "lifecycleRules": []
    } ]
}

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/v1/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": "30f20426f0b1",
        "bucketId": "4a48fe8875c6214145260818",
        "bucketInfo": {},
        "bucketName" : "Kitten-Videos",
        "bucketType": "allPrivate",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId" : "5b232e8875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Puppy-Videos",
        "bucketType": "allPublic",
        "lifecycleRules": []
    },
    {
        "accountId": "30f20426f0b1",
        "bucketId": "87ba238875c6214145260818",
        "bucketInfo": {},
        "bucketName": "Vacation-Pictures",
        "bucketType" : "allPrivate",
        "lifecycleRules": []
    } ]
}

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/v1/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": "30f20426f0b1",
            "bucketId": "4a48fe8875c6214145260818",
            "bucketInfo": {},
            "bucketName" : "Kitten-Videos",
            "bucketType": "allPrivate",
            "lifecycleRules": []
        },
        {
            "accountId": "30f20426f0b1",
            "bucketId" : "5b232e8875c6214145260818",
            "bucketInfo": {},
            "bucketName": "Puppy-Videos",
            "bucketType": "allPublic",
            "lifecycleRules": []
        },
        {
            "accountId": "30f20426f0b1",
            "bucketId": "87ba238875c6214145260818",
            "bucketInfo": {},
            "bucketName": "Vacation-Pictures",
            "bucketType" : "allPrivate",
            "lifecycleRules": []
        } ]
}