Over time, the Backblaze B2 APIs get updated to support new features, and to make them easier to use. When changes are not compatible, we make a new version of the API, and keep supporting the old versions.

Specifying 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 starts with something like /b2api/v2/. The "v2" is the version number.

The current version number is v2.

In general, you should always used the latest version number. And you should update your client code periodically to take advantage of the latest version. The latest version will have the latest performance improvements, and may be the only place to get the latest features. In general, our goal is that upgrading from one version to the next will be 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

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 ("v2") in the path. This remains the same as long as the API stays 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 will continue to be supported for a while.

When a new version of the APIs is created, usually only a few of the calls actually change. The new version number is used to get the new version of those calls, and 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'll need to 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 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.
Allowing a call that was not allowed before.

These are incompatible changes, and won't happen without going 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 v2. The documentation pages for each API call describe v2, with the differences between v1 and v2 in the "API Versions" section of the page.

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

v2: Object Lock (May 11, 2021)

To allow B2 clients 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 B2 clients 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: Remove application key workaround (Sept 13, 2018)

Version v2 cleans up the workaround introduced in the August 9, 2018 release. It goes back to returning exactly what you ask for in a query, and no longer has implicit filters implied by the application key being used. It's easier to explain, and easier to know what to expect in response to a query, if the results of the query do not depend on the application key you happened to use.

See Application Keys for information on how to work with application keys that have bucket and file name restrictions.

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

When the application 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 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).

And because making a new API version is a good time to drop deprecated fields, these fields are not 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: Workaround for existing applications and application keys (August 9, 2018)

Because some existing integrations were having trouble with the incompatibility in the July 26 release, we broke our own rules and changed the behavior of some calls to help existing software support the new Application 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 things that are allowed by the application key. When you ask for all buckets, or for files in a bucket, the query is automatically restricted to the things that your application key is allowed access to.

v1: Application keys (July 26, 2018)

New calls to manage application 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 application key that allows access to only one bucket.

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

New field allowed in response from b2_authorize_account , which includes information about what the application 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 once you authenticate, all of the calls will be authorized. If you authenticate with an application 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 didn't anticipate the quick uptake of users making these keys and using them in existing integrations which, very reasonably, weren't 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 B2 Storage service launched.