Source Code Bundles
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
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.
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
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
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.
bucketTypefor buckets, and
actionfor file versions both say that they may be extended in the future.
The current version is
The documentation pages for each API call describe
v2, with the
v2 in the "API Versions"
section of the page.
The list of versions below describes the changes in each version.
v2: Remove application key workaround (Sept 13, 2018)
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
bucketName, in addition to the
bucketIdthat 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
b2_list_file_names now returns
b2_list_file_versions now returns
b2_list_unfinished_large_files now returns
contentLength(always null), and
b2_start_large_file now returns
contentLength(always null), and
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
The responses from
b2_hide_file, no longer contain
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
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)
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.
namePrefix parameter to
so that you can restricted the results to just some
files. This is especially useful with application
keys that have file name restrictions.
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.