Download Files with the Native API

Downloading files using the Backblaze B2 Cloud Storage Native API is simple and straightforward.

Download Files

There are two ways to download files. You can use the b2_download_file_by_id operation to download a file if you have the file ID. Use the b2_download_file_by_name operation if you have the file name. Both of these methods download only one file at a time.

Applications that intend to use the RANGE header to multithread the download of files can use the more efficient HEAD request to fetch file information, as opposed to making an initial call to download a single byte.

Some buckets may be private and require you to have an authorization token to access the files in the bucket (see b2_authorize_account). Alternatively, you can use the b2_get_download_authorization operation as an authorization token to access files with a specific filename prefix.

Errors that are returned from b2_download_file_by_id and b2_download_file_by_name are usually due to a bad request, or the request is unauthorized. Another cause of these errors may be because the file was previously deleted and can no longer be found.

• 400 Bad Request
  • bad_request Returns a message that describes the issue.
• 401 Unauthorized
  • missing_auth_token There is no Authorization header.
  • bad_auth_token The authorization token is not valid.
  • expired_auth_token The authorization token has expired.
  • unauthorized The authorization token that you used does not allow access to this file.
• 404 Not Found
  • not_found The bucket or file does not exist.
• 416 Range Not Satisfiable
  • range_not_satisfiable The request is outside the size of the file content.
• 429 Too Many Requests
  • too_many_requests Your account has too many concurrent downloads.
• 5xx
  • There is a problem in the service. Retry with exponential back-off.

Download Files by ID

Requests to b2_download_file_by_id follow a typical pattern, but you must use the downloadUrl instead of the apiUrl that is returned by b2_authorize_account.

The URL to download a file by ID looks like the following example:

    https://f123.backblazeb2.com/b2api/v3/b2_download_file_by_id

Download Files by Name

The URL to download a file by name a GET request, and it is comprised of the following parts:

1. The downloadUrl that is returned by b2_authorize_account
2. /bucketName
3. /fileName

The download URL is similar to the following example:

$ curl https://f001.backblazeb2.com/file/photos/cats/kitten.jpg

The file is returned, as well as the information about the file including its SHA1 and MIME type in the HTTP headers.

List Files

You can call b2_list_file_names to get a list of the files in a bucket, and call b2_list_file_versions to list all of the versions of the files in a bucket. For more information, see File Versions.

View Uploaded Files

If you upload a file called cats/kitten.jpg to a bucket called cute_pictures, you can view the file in a browser with a URL that looks like the following example:

https://f001.backblazeb2.com/file/cute_pictures/cats/kitten.jpg

The first part of the URL is the download URL that is returned from the b2_authorize_account call, /file/, the bucket name, /, and the file name.

Download in Parallel

You can use the URL and authorization token that are returned from the b2_authorize_account operation by multiple downloading threads. You can download in parallel to increase overall throughput.

Unauthorized Errors

You are not able to view the URLs for files online from a bucket that is set to allPrivate. If you use either the Friendly or Native URL from a file through the Backblaze web console, and the following error is returned, you should check your bucket settings.

{
   "code": "unauthorized",
   "message": "unauthorized",
   "status": 401
}

To use the Friendly or Native URLs for files through the Backblaze web console, you must change your bucket setting to allPublic. You can edit your bucket settings on the Buckets page of your account. Click Bucket Settings, and change the setting to allPublic.