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 are calling version 2, the current version, of b2_list_file_names:

    https://api123.backblazeb2.com/b2api/v2/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/v2/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/v2/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/v2/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 it 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 # 63 char max: letters, digits, and hyphen -
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" : "e1256f0973908bfc71ed0c1z",
    "accountId" : "12f634bf3cbz",
    "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=... # Application Key from 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 # 63 char max: letters, digits, and hyphen -
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. First call b2_get_upload_url to retrieve specific data to pass in.

ACCOUNT_ID=... # Application Key from the Backblaze web site
ACCOUNT_AUTH_TOKEN=... # Comes from the b2_authorize_account call
BUCKET_ID=... # ID for the bucket to upload to
API_URL=... # Comes from the b2_authorize_account call

curl \
    -H "Authorization: $ACCOUNT_AUTH_TOKEN" \
    -d "{\"bucketId\": \"$BUCKET_ID\"}" \
    "$API_URL/b2api/v2/b2_get_upload_url"

This will return the following response, including the upload authorizationToken and the uploadUrl to use.

{
  "authorizationToken": "4_0028bc628f87f040000000001_019e8f5e_263f9e_upld_Yr3aQphj7BktivNK60zSnoh6UDU=",
  "bucketId": "e1256f0973908bfc71ed0c1z",
  "uploadUrl": "https://pod-000-1143-18.backblaze.com/b2api/v2/b2_upload_file/e1256f0973908bfc71ed0c1z/c002_v0001143_t0002"
}

Upload call can now be completed as follows:

FILE_TO_UPLOAD=~/Downloads/logo.jpeg # Name and URL of the file to upload
MIME_TYPE=b2/x-auto # Mime type of the file. X-auto can also be leveraged.
SHA1_OF_FILE=$(openssl dgst -sha1 $FILE_TO_UPLOAD | awk '{print $2;}') # SHA1 of the file
UPLOAD_URL=... # From the b2_get_upload_url call
UPLOAD_AUTHORIZATION_TOKEN=... # From the b2_get_upload_url call

curl \
    -H "Authorization: $UPLOAD_AUTHORIZATION_TOKEN" \
    -H "X-Bz-File-Name: $FILE_TO_UPLOAD" \
    -H "Content-Type: $MIME_TYPE" \
    -H "X-Bz-Content-Sha1: $SHA1_OF_FILE" \
    -H "X-Bz-Info-Author: unknown" \
    --data-binary "@$FILE_TO_UPLOAD" \
    $UPLOAD_URL

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

{
    "fileId" : "4_he1256f0973908bfc71ed0c1z_f000000000000472a_d20140104_m032022_c001_v0000123_t0104",
    "fileName" : "typing_test.txt",
    "accountId" : "12f634bf3cbz",
    "bucketId" : "e1256f0973908bfc71ed0c1z",
    "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

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

JSON Error Structure

Example:

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