Calling the API

Most of the API calls for B2 Cloud Storage accept a POST with JSON data, and return JSON data. The code samples for each of the calls show how to do that in a variety of languages.

Constructing the URL

For most calls, you construct the URL by combining four things:

  1. The apiUrl returned by b2_authorize_account
  2. /b2api
  3. /vversionNumber
  4. /apiName

The version number says which version of the API you want to call. (See API Versions for more details.) The API name says which API entry point you want to call. The resulting URL will look like this if you want to call version 5 of b2_list_file_names:

    https://api123.backblazeb2.com/b2api/v5/b2_list_file_names

Authorizing an Account

The call to b2_authorize_account is special because the API URL is fixed: https://api.backblazeb2.com, so the full URL will look like this:

    https://api.backblazeb2.com/b2api/v5/b2_authorize_account

Uploading Files

When uploading files, just use the exact URL returned from b2_get_upload_url or b2_get_upload_part_url. The version number in that URL will match the version number of the call that returned it. The headers of the upload request hold the parameters, and the body holds the file being uploaded.

The URL to upload a file looks like this:

    https://pod-000-1013-02.backblaze.com/b2api/v5/b2_upload_file/8f433564b42f9c515e21021e/c001_v0001013_t0020

Downloading Files by ID

Requests to b2_download_file_by_id follow the normal pattern, but use the downloadUrl instead of the apiUrl returned by b2_authorize_account.

The URL to download a file by ID looks like this:

    https://f123.backblazeb2.com/b2api/v5/b2_download_file_by_id

Downloading Files by Name

The URL to download a file by name is made of three parts:

  1. The downloadUrl returned by b2_authorize_account
  2. /bucketName
  3. /fileName

The download URL will look like this:

    https://f123.backblazeb2.com/file/my-bucket/myFile.txt

Status Code Returned

For all calls to B2, the HTTP status code returned indicates success or failure. Unsuccessful calls return a JSON error structure in the body of the response that includes the status, a "code" that is a short string, and a "message" intended only for humans.

A status of 200 (OK) means success, and 206 (Partial Content) means success when downloading using the Range header. Any code in the 400 or 500 range is a failure. See the section below on Error Handling for details. At present, B2 does not use redirects (status codes in the 300 range).

POST JSON -> JSON

This is the normal case for API calls to B2. You create a request as a JSON object, POST in to the B2 service, and get a JSON object in the response.

This is a simple example using curl on the command-line:

ACCOUNT_ID=... # Comes from your account page on the Backblaze web site
ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call
API_URL=... # Comes from the b2_authorize_account call
BUCKET_NAME=any_name_you_pick # 50 char max: letters, digits, “-“ and “_”
BUCKET_TYPE=allPrivate # Either allPublic or allPrivate

curl -H "Authorization: $ACCOUNT_AUTH_TOKEN" \
    -d "{\"accountId\":  \"$ACCOUNT_ID\", \"bucketName\": \"$BUCKET_NAME\", \"bucketType\": \"$BUCKET_TYPE\"}' \
    "$API_URL/b2api/v2/b2_create_bucket"

Will return this:

{
    "bucketId" : "4a48fe8875c6214145260818",
    "accountId" : "010203040506",
    "bucketName" : "any_name_you_pick",
    "bucketType" : "allPrivate"
}

GET -> JSON

All API calls that accept POST-ed JSON also accept the parameters as URL query parameters. This is much more convenient for ad-hoc requests that you type by hand, and for using in a browser.

This request is equivalent to the one above:

ACCOUNT_ID=... # Comes from your account page on the Backblaze web site
ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call
API_URL=... # Comes from the b2_authorize_account call
BUCKET_NAME=any_name_you_pick # 50 char max: letters, digits, “-“ and “_”
BUCKET_TYPE=allPrivate # Either allPublic or allPrivate

curl -H "Authorization: $ACCOUNT_AUTH_TOKEN" \
    "$API_URL/b2api/v2/b2_create_bucket?accountId=$ACCOUNT_ID&bucketName=$BUCKET_NAME&bucketType=$BUCKET_TYPE"

Uploading Files

When you upload a file, the body of the POST is the file being uploaded, and the other information is passed in the HTTP headers.

curl \
    -H 'Authorization: $BUCKET_AUTH_TOKEN' \
    -H 'X-Bz-File-Name: typing_test.txt' \
    -H 'Content-Type: text/plain' \
    -H 'X-Bz-Content-Sha1: bae5ed658ab3546aee12f23f36392f35dba1ebdd' \
    -H 'X-Bz-Info-Author: unknown' \
    -d @typing_test.txt \
    $UPLOAD_URL

This will return a JSON response containing the File ID of the new file:

{
    "fileId" : "4_h4a48fe8875c6214145260818_f000000000000472a_d20140104_m032022_c001_v0000123_t0104",
    "fileName" : "typing_test.txt",
    "accountId" : "d522aa47a10f",
    "bucketId" : "4a48fe8875c6214145260818",
    "contentLength" : 46,
    "contentSha1" : "bae5ed658ab3546aee12f23f36392f35dba1ebdd",
    "contentType" : "text/plain",
    "fileInfo" : {
       "author" : "unknown"
    }
}

Downloading Files

To download a file by name, you simply GET a path built from the download URL that b2_authorize_account returned, /file/, the name of the bucket, and the name of the file, such as:

curl https://f001.backblazeb2.com/file/photos/cats/kitten.jpg

The file will be returned, and the information about the file, including its SHA1 and MIME type is in the HTTP headers.

Error Handling

Failures to connect to the B2 servers, and networking problems in general can cause errors, which are reported in the normal way.

If you get a response from B2, the HTTP status code will tell you whether it is an error or not. A status of 200 (OK) means that the call was successful. For most calls, a successful response contains the JSON that is described in the API documentation. Any code other than 200 is an error, and the response will contain a JSON error structure indicating what went wrong. The documentation for each API includes information on specific errors return for that API; the general classes of errors are:

HTTP Status Code

200

The request was successful, and the response contains the JSON structure described in the page for the call.

400

BAD REQUEST - There is a problem with a passed in request parameters - the JSON error structure returned will contain an error code of bad_request and a human-readable error message describing the problem.

401

UNAUTHORIZED

When calling b2_authorize_account, this means that there was something wrong with the accountId/applicationKeyId or with the applicationKey that was provided. The code unauthorized means that the application key is bad. The code unsupported means that the application key is only valid in a later version of the API.

When uploading data using b2_upload_file or b2_upload_part, this can mean a variety of things. Try calling b2_get_upload_url or b2_get_upload_part_url again to get a new upload target and auth token. That call will either work or provide a meaningful error code.

For all other API calls, the code returned tells you what to do. The code unauthorized means that the auth token is valid, but does not allow you to make this call with these parameters. When the code is either bad_auth_token or expired_auth_token you should call b2_authorize_account again to get a new auth token.

403

FORBIDDEN - You have a reached a storage cap limit, or account access may be impacted in some other way; see the human-readable message.

408

REQUEST TIMEOUT - The service timed out trying to read your request.

429

TOO MANY REQUESTS - B2 may limit API requests on a per-account basis.

500

INTERNAL ERROR - An unexpected error has occurred.

503

SERVICE UNAVAILABLE - The service is temporarily unavailable. The human-readable message identifies the nature of the issue, in general we recommend retrying with an exponential backoff between retries in response to this error.

See the Integration Checklist for more detailed information on handling errors.

JSON Error Structure

status

The numeric HTTP status code. Always matches the status in the HTTP response.

code

A single-identifier code that identifies the error.

message

A human-readable message, in English, saying what went wrong.

Example:

{
    "status" : 400,
    "code" : "invalid_bucket_name",
    "message" : "bucket name is too long"
}