Native API Versions

Over time, Backblaze updates the APIs to support new features and to make them easier to use. When changes are not compatible, we make a new version of the API, but we continue to support old versions.

Specify an API Version

When you call an API, you include the API version number in the URL of the call. The path for an API call begins with /b2api/v3/, for example. The "v3" is the version number.

The current version number is v3.

In general, you should always use the latest version number, and you should update your client code periodically to take advantage of the latest version. The latest version has the latest performance improvements, and it may be the only place to get the latest features. Our goal is to make upgrading from one version to the next version straightforward.

Support for Old Versions

Backblaze does not have any plans to stop supporting old versions. If we ever do make such plans, we will announce them at least a year in advance to give you plenty of time to update your code.

Compatibility

The URLs for the APIs include a version number ("v3") in the path. This remains the same as long as the API stays compatible. When we have to make an incompatible change, the API gets a new version number ("v4") and we continue to support the old API.

Typically, when Backblaze creates a new version of the API, only a few of the calls change. The new version number is used to get the new version of those calls, and it can also be used for all of the other calls. For example, if v37 is released with an incompatible change to b2_create_key, you must use v37 to access the new features. You can also use v37 with all other API calls, and they will behave just as they did in v36.

Some API changes are compatible and do not 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 in which leaving out the field maintains the old behavior.
• Adding a new field in a response. Your code should ignore any fields that it does not expect.
• Allowing a call that was not allowed before.

These are incompatible changes, and they will not happen without updating to a new API version number:

• Changing the behavior of an existing call with existing parameters.
• 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.

Version History

The current version is v3. The documentation pages for each API call describe v3, with the previous version differences in the "API Versions" section of the page.

The list of versions below describes the changes in each version.

v3: b2_authorize_account (September 23, 2021)

 The initial versions of b2_authorize_account were specific to the B2 Storage service. In v3, we added the Partner APIs as a new API suite. The changes in v3 extend b2_authorize_account to work with multiple API suites, including the B2 Storage and Partner APIs:

• b2_authorize_account now returns a data structure that groups the information you need by API suite. For each suite enabled, it provides the information you need to call those APIs.
  
  
• Please use v2 with b2_authorize_account for B2 Native API calls if the Partner API is enabled on your account.

v2: Object Lock (May 11, 2021)

To allow Backblaze B2 you to view Object Lock information, some API calls return more fields:

• b2_list_file_names now returns fileRetention, legalHold.
• b2_list_file_versions now returns fileRetention, legalHold.

v2: Server-Side Encryption (March 5, 2021)

To allow Backblaze B2 you to view server-side encryption information, some API calls return more fields:

• b2_list_file_names now returns serverSideEncryption.
• b2_list_file_versions now returns serverSideEncryption.

v2: App Key Workaround (Sept 13, 2018)

Version v2 cleans up the workaround introduced in the August 9, 2018 release. It returns exactly what you request in a query, and it no longer has implicit filters implied by the app key that you use. 

For information about how to work withapp keys that have bucket and file name restrictions, click here.

To make it easier to work withapp keys with restricted access:

• When theapp key is restricted to a bucket, the response from b2_authorize_account now includes the bucketName, in addition to the bucketId that was already there.

To simplify Backblaze B2 clients, all API calls that return information about files now return the same structure. This means that some calls return more fields:

• b2_hide_file now returns accountId, bucketId.
• b2_list_file_names now returns accountId, bucketId.
• b2_list_file_versions now returns accountId, bucketId.
• b2_list_unfinished_large_files now returns action (always "upload"), contentLength (always null), and contentSha1 (always null).
• b2_start_large_file now returns action (always "upload"), contentLength (always null), and contentSha1 (always null).

These fields are no longer present when you use v2:

• The response from b2_authorize_account no longer contains minimumPartSize. Use recommendedPartSize and absoluteMinimumPartSize instead.
• The responses from b2_list_file_names, b2_list_file_versions, and b2_hide_file, no longer contain size. Use contentLength instead.

v1: Existing Applications and App Keys (August 9, 2018)

We changed the behavior of some calls to help existing software support the new app keys feature. The updated v1 as of this release implicitly restricts b2_list_buckets, b2_list_file_names, b2_list_file_versions, and b2_list_unfinished_large_files to the items that are allowed by the app key. When you ask for all buckets or for files in a bucket, the query is automatically restricted to the items that your app key is allowed access to.

v1: App Keys (July 26, 2018)

New calls to manage app keys: b2_create_key, b2_list_keys, b2_delete_key, and b2_create_key.

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 app key that allows access to only one bucket.

New optional namePrefix parameter to b2_list_unfinished_large_files so that you can restrict the results to just some files. This is especially useful with app keys that have file name restrictions.

New field allowed in response from b2_authorize_account, which includes information about what the app key allows you to do, and restrictions it has on bucket and file name prefix.

This release was incompatible with previous releases because it broke an (unwritten) rule that after you authenticate, all of the calls will be authorized. If you authenticate with an app key that has restricted capabilities, is restricted to a bucket, or is restricted to a file name prefix, some calls will return a 401 Unauthorized.

We did not anticipate the quick uptake of users making these keys and using them in existing integrations which, very reasonably, were not prepared for the restrictions, which is the reason for the workaround released on August 9.

v1: Original Release (September 22, 2015)

Version 1 of the APIs launched when the Backblaze B2 service launched.