b2_list_buckets
    • Dark
      Light

    b2_list_buckets

    • Dark
      Light

    Article Summary

    Post
    /b2api/v3/b2_list_buckets

    Lists buckets alphabetically by 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.

    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.

    Header parameters
    Authorization
    stringRequired

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

    Body parameters
    object
    accountId
    string Required

    Your account ID.

    ExampleACCOUNT_ID
    bucketId
    string

    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.

    Example4a48fe8875c6214145260818
    bucketName
    string

    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.

    ExamplemyBucketName
    bucketTypes
    Array of string

    If present, this will be used 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.

    Example[ "allPublic", "allPrivate" ]
    string
    Responses
    200

    The request succeeded.


    The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.

    Expand All
    object
    buckets
    Array of object

    An array of bucket objects.

    Example[ { "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 } ]
    object
    accountId
    string

    The account that the bucket is in.

    bucketId
    string

    The unique ID of the bucket.

    Example3f46fe8276c62b414506021y
    bucketName
    string

    The unique name of the bucket

    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.

    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.

    isClientAuthorizedToRead
    boolean
    value
    object
    defaultRetention
    object
    mode
    string
    period
    string
    isFileLockEnabled
    boolean
    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
    ExampleTrue
    value
    object
    algorithm
    string
    ExampleAES256
    mode
    string
    ExampleSSE-B2
    lifecycleRules
    object

    The list 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
    daysFromUploadingToHiding
    integer
    fileNamePrefix
    string
    replicationConfiguration
    object

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

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

    Example3
    options
    Array of string

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

    Example[ "s3" ]
    string
    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.
    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.
    403
    statuscodedescription
    403transaction_cap_exceededTransaction 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.

    Was this article helpful?