b2_download_file_by_name

11 Sep 2026

Print
Dark
Light

b2_download_file_by_name

Updated on 11 Sep 2026

Print
Dark
Light

Article summary

Did you find this summary helpful?

Thank you for your feedback

Get

/file/{BUCKET_NAME}/{FILE_NAME}

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 using a bucket name and file name

The base URL to use comes from the b2_authorize_account call, and looks something like https://f345.backblazeb2.com. The "f" in the URL stands for "file", and the number is the cluster number containing your account. To this\ base, you add "file/", your bucket name, a "/", and then the name of the file. The file name may itself include more "/" characters.

If you have a bucket named "photos", and a file called "cute/kitten.jpg", then the URL for downloading that file would be: https://f345.backblazeb2.com/file/photos/cute/kitten.jpg.

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.

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)

For information on all API versions, view our API changelog.

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.

Alternatively, a download authorization token obtained from b2_get_download_authorization can be used to access files whose names begin with the filename prefix that was used to generate the download authorization token.

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 byte-range request that returns part of the stored file.

NOTE: Only byte-range requests with a single range of bytes are supported.

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.

Path parameters

BUCKET_NAME

stringRequired

The name given to the bucket. Bucket names can consist of letters, digits, hyphens ("-"), and periods ("."). Bucket names cannot start with "b2-", these are reserved for internal Backblaze use. A bucket name must not begin or end with a period, must not contain two adjacent periods, and must not be formatted as an IPv4 address (for example, 192.168.0.1).

FILE_NAME

stringRequired

The name of the file.

Query parameters

Authorization

string

An authorization token can be provided in the URL query string instead of being passed in the HTTP header. An account authorization token obtained from b2_authorize_account will allow access to all files in a private bucket. A download authorization token obtained from b2_get_download_authorization will allow access to files whose names begin with the filename prefix used to generate the download authorization token. For example:

https://f345.backblazeb2.com/file/photos/cute/kitten.jpg?Authorization=3_20160803004041_53982a92f631a8c7303e3266_d940c7f5ee17cd1de3758aaacf1024188bc0cd0b_000_20160804004041_0006_dnld

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 or in Object Lock-enabled buckets), this request will be rejected. See Files for further details about HTTP header size limit.

Requests with this specified must also have an authorization token. If the token was generated with b2_get_download_authorization, this b2-content-disposition must have the same value that was provided to b2_get_download_authorization.

b2ContentLanguage

string

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

The value must match the grammar specified in RFC 2616. Note that this file info will not be included in downloads as a x-bz-info-b2-content-language header. Instead, it (or the value specified in a request) will be in the Content-Language.

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.