b2_download_file_by_name
    • Dark
      Light

    b2_download_file_by_name

    • Dark
      Light

    Article Summary

    Get
    /file/{BUCKET_NAME}/{FILE_NAME}

    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 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)

    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 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.

    Path parameters
    BUCKET_NAME
    stringRequired

    The name given to the bucket. Bucket names can consist of letters, digits, and "-". Bucket names cannot start with "b2-", these are reserved for internal Backblaze use.

    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.


    Requests with this specified must also have an authorization token.


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

    b2Expires
    string

    If this is present, B2 will use it as the value of the 'Expires' header, overriding any 'b2-expires' 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-expires header. Instead, it (or the value specified in a request) will be in the Expires.


    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.


    Requests with this specified must also have an authorization token.


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

    b2CacheControl
    string

    If this is present, B2 will use it as the value of the 'Cache-Control' header, overriding any 'b2-cache-control' 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-cache-control header. Instead, it (or the value specified in a request) will be in the Cache-Control.


    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.


    Requests with this specified must also have an authorization token.


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

    b2ContentEncoding
    string

    If this is present, B2 will use it as the value of the 'Content-Encoding' header, overriding any 'b2-content-encoding' 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-encoding header. Instead, it (or the value specified in a request) will be in the Content-Encoding.


    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.


    Requests with this specified must also have an authorization token.


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

    b2ContentType
    string

    If this is present, B2 will use it as the value of the 'Content-Type' header, overriding any 'Content-Type' 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-type header. Instead, it (or the value specified in a request) will be in the Content-Type.


    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.


    Requests with this specified must also have an authorization token.


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

    Responses
    200

    The request succeeded.


    The response headers include the Content-Type that was specified when the file was uploaded. They also include the X-Bz-FileName and X-Bz-Content-Sha1 headers, plus X-Bz-Info-* headers for any custom file info that was provided with the upload. The X-Bz-FileName uses percent-encoding, as if it were a URL parameter.

    Headers
    Content-Length
    integer
    Size of the message body, in bytes.
    Content-Type
    string
    The original media type of the resource
    X-Bz-File-Id
    string
    Id of file.
    X-Bz-File-Name
    string
    Name of file.
    X-Bz-Content-Sha1
    string
    The SHA1 checksum of the content of the file.
    X-Bz-Info-*
    string
    Headers for any custom file info that was provided with the upload.
    X-Bz-Upload-Timestamp
    integer
    Timestamp from when the upload began.
    Content-Disposition
    string
    Computed from the b2-content-disposition provided when the file was uploaded or specified during the download request.
    Content-Language
    string
    Computed from the b2-content-language provided when the file was uploaded or specified during the download request.
    Expires
    integer
    Computed from the b2-expires provided when the file was uploaded or specified during the download request.
    Cache-Control
    string
    Computed from the download request, otherwise the value provided when the file was uploaded, otherwise the value specified on the bucket.
    Content-Encoding
    string
    Computed from the b2-content-encoding provided when the file was uploaded or specified during the download request.
    X-Bz-Server-Side-Encryption
    string
    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
    string
    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
    string
    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.
    X-Bz-File-Retention-Mode
    string
    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
    integer
    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
    string
    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
    string
    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).
    400
    statuscodedescription
    400bad_bucket_idThe requested bucket ID does not match an existing bucket.
    400bad_requestThe request had the wrong fields or illegal values. The message returned with the error will describe the problem.
    object
    status
    integer

    The numeric HTTP status code. Always matches the status in the HTTP response.

    Example400
    code
    string

    A single-identifier code that identifies the error.

    Exampleinvalid_bucket_name
    message
    string

    A human-readable message, in English, saying what went wrong.

    Examplebucket name is too long
    401
    statuscodedescription
    401bad_auth_tokenThe auth token used is not valid. Call b2_authorize_account again to either get a new one, or an error message describing the problem.
    401expired_auth_tokenThe auth token used has expired. Call b2_authorize_account again to get a new one.
    401unauthorizedThe auth token used is valid, but does not authorize this call with these parameters. The capabilities of an auth token are determined by the application key used with b2_authorize_account.
    403
    statuscodedescription
    403access_deniedThe provided customer-managed encryption key is wrong.
    403download_cap_exceededUsage cap exceeded.
    403transaction_cap_exceededTransaction cap exceeded. To increase your cap, sign in to your B2 Cloud Storage account online. Then select the Caps & Alerts link in the B2 Cloud Storage section of the sidebar.
    404
    statuscodedescription
    404not_foundFile is not in B2 Cloud Storage.
    416
    statuscodedescription
    416range_not_satisfiableThe Range header in the request is valid but cannot be satisfied for the file.

    Was this article helpful?