b2_download_file_by_id

Print
Dark
Light

b2_download_file_by_id

Print
Dark
Light

Article Summary

Share feedback

Thanks for sharing your feedback!

Get

/b2api/v3/b2_download_file_by_id

PLEASE NOTE:

This API request is now being described as a GET request and not a POST request, as was the case in previous versions of our documentation.

We made this update because we believe that an API call that retrieves data and does not alter state is more accurately represented as a GET request.

You may still make a POST request to this endpoint by simply submitting a JSON-formatted request body containing the parameters, with Content-Type set to application/json.

Downloads one file from B2

The response contains the following headers, which contain the same information they did when the file was uploaded:

Content-Length
Content-Type
X-Bz-File-Id
X-Bz-File-Name
X-Bz-Content-Sha1
X-Bz-Info-* (except for the ones that set other response headers, such as b2-content-disposition)

The response also includes a header with the timestamp from when the upload began:

X-Bz-Upload-Timestamp

The following headers may be present:

Content-Disposition : computed from the b2-content-disposition provided when the file was uploaded or specified during the download request.
Content-Language : computed from the b2-content-language provided when the file was uploaded or specified during the download request.
Expires : computed from the b2-expires provided when the file was uploaded or specified during the download request.
Cache-Control : computed from the download request, otherwise the value provided when the file was uploaded, otherwise the value specified on the bucket.
Content-Encoding : computed from the b2-content-encoding provided when the file was uploaded or specified during the download request.
X-Bz-Server-Side-Encryption : if the file was encrypted with SSE-B2, then the value is the algorithm used for encryption; otherwise omitted.
X-Bz-Server-Side-Encryption-Customer-Algorithm : if the file was encrypted with SSE-C, then the value is the algorithm used for encryption; otherwise omitted.
X-Bz-Server-Side-Encryption-Customer-Key-Md5 : if the file was encrypted with SSE-C, then the value is the MD5 digest of the customer-managed encryption key used for encryption, otherwise omitted.

If the file is in a bucket that is Object Lock-enabled, then the following headers may also be present:

X-Bz-File-Retention-Mode : if Object Lock retention settings are enabled for the file and the client has the readFileRetentions application key capability, then the value is the file retention mode (governance or compliance).
X-Bz-File-Retention-Retain-Until-Timestamp : if Object Lock retention settings are enabled for the file and the client has the readFileRetentions application key capability, then the value is the file retention timestamp, specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC.
X-Bz-File-Legal-Hold : if Object Lock legal hold has been enabled or disabled for the file and the client has the readFileLegalHolds application key capability, then the value is the current status (on or off).
X-Bz-Client-Unauthorized-To-Read : if the client does not have readFileRetentions and/or readFileLegalHolds application key capabilities, then the value will include names of headers which are not present because the client does not have appropriate permissions to access those values (e.g., X-Bz-File-Retention-Mode,X-Bz-File-Retention-Retain-Until-Timestamp).

When only the header information is required, use the more efficient HEAD request rather than requesting a single byte of the file.

If the bucket containing the file is set to require authorization, then you must supply the account's auth token in the Authorization header.

Because errors can happen in network transmission, you should check the SHA1 of the data you receive against the SHA1 returned in the X-Bz-Content-Sha1 header.

The URL to use for downloading starts with the downloadUrlreturned by b2_authorize_account, followed by/b2api/v3/b2_download_file_by_id, and looks like this:https://f001.backblazeb2.com/b2api/v3/b2_download_file_by_id.

As with normal API calls, most of the request information can either be posted as JSON, or put in the URL query parameters. See above for details. Unlike the other API calls, the response is not JSON, but is the contents of the file.

API Versions

v1: Application keys (July 26, 2018)

Incompatible change: After calling b2_authorize_account with an application key that does not have the right permissions, this call will return a 401 Unauthorized.

v1: Original release (September 22, 2015)

Header parameters

Authorization

string

An account authorization token, obtained from b2_authorize_account.
The token must have the readFiles capability.

This is required if the bucket containing the file is not public. It is optional for buckets that are public. This must be in the request's headers.

X-Bz-Server-Side-Encryption-Customer-Algorithm

string

The algorithm to use when encrypting/decrypting a file using SSE-C encryption. The only currently supported value is AES256.

X-Bz-Server-Side-Encryption-Customer-Key

string

The base64-encoded AES256 encryption key when encrypting/decrypting a file using SSE-C encryption.

X-Bz-Server-Side-Encryption-Customer-Key-Md5

string

The base64-encoded MD5 digest of the X-Bz-Server-Side-Encryption-Customer-Key when encrypting/decrypting a file using SSE-C encryption.

Range

string

A standard byte-range request, which will return just part of the stored file.

The value "bytes=0-99" selects bytes 0 through 99 (inclusive) of the file, so it will return the first 100 bytes. Valid partial byte ranges will cause the response to contain a Content-Range header that specifies which bytes are returned. Invalid byte ranges or a byte range that encloses the entire stored file's content will just return the whole file.

Note that the SHA1 checksum returned is still the checksum for the entire file, so it cannot be used on the byte range.

The status code for a successful response to a Range request is 206 Partial Content when only part of the stored file is returned. The status code for the response is 200 OK (and no Content-Range header is included) when the whole file is returned.

NOTE: If your use case requires the bytes=0- header to receive a 206 Partial Content response with the Content-Range, please use our S3-Compatible API.

This must be in the request's headers.

Query parameters

fileId

stringRequired

The file ID that was returned from b2_upload_file. It can also be found using b2_list_file_versions.

b2ContentDisposition

string

If this is present, B2 will use it as the value of the 'Content-Disposition' header, overriding any 'b2-content-disposition' specified when the file was uploaded.

The value must match the grammar specified in RFC 6266. Parameter continuations are not supported. 'Extended-value's are supported for charset 'UTF-8' (case-insensitive) when the language is empty. Note that this file info will not be included in downloads as a x-bz-info-b2-content-disposition header. Instead, it (or the value specified in a request) will be in the Content-Disposition.

If including this header in the response exceeds the 7000-byte overall limit (2048 bytes for files encrypted with SSE), this request will be rejected. See Files for further details about HTTP header size limit.