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.

For all calls to B2, the HTTP status code returned indicates success or failure. A status of 200 (OK) means success. 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/v1/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/v1/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.

Compatibility

Over time, the B2 APIs will grow to support new features. As they grow, the APIs will change.

The URLs for the APIs include a version number ("v1") in the path. This remains the same as long as the API stats compatible. When we have to make an incompatible change, the new version of the API gets a new version number ("v2"), and the old API stays supported while client code transitions to the new API. We will give you plenty of time to make the change when a new version is created.

Some API changes are compatible, and don't require a version change. These can happen at any time, and your code should be able to deal with them:

  • Adding new API entry points.
  • Allowing a wider range of values in an input field. For example, allowing a bigger number in maxFileCount in b2_list_file_names.
  • Adding a new optional field in a request, where leaving out the field keeps the old behavior.
  • Adding a new field in a response. Your code should ignore any fields it doesn't expect.

These are incompatible changes, and won't happen without going to a new API version number:

  • Disallowing previously allowed values. For example, shortening the maximum length of a bucket name.
  • Adding new required fields in a request.
  • Removing a field from a request.
  • Removing a field from a response.
  • Returning a wider set of values in a response, unless the documentation explicitly says that it could happen.
    Note that bucketType for buckets, and action for file versions both say that they may be extended in the future.

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

400

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

401

UNAUTHORIZED - Returned while uploading, indicates the upload URL has expired; A new upload URL can be obtained from b2_get_upload_url or b2_get_upload_part_url. Returned from b2_authorize_account, indicates the account ID is wrong, the account does not have B2 enabled, or the application key is not valid. For all other APIs, there is a problem with the Authorization Token as indicated in the human-readable message. A new Authorization Token can be obtained from b2_authorize_account.

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. The human-readable message is intended for Backblaze engineering use, to help isolate the problem.

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"
}