The B2 Native API can be used to access functionality, such as application key management and lifecycle rules. For more information about the B2 Native API and specific how-to guides, click here. Using the B2 Native API, you can: Upload, download, and delete files Create and manage the buckets that hold files Manage the configuration of your account Prerequisites To get started, you will need to have "B2 Cloud Storage" enabled in your account settings. For detailed instructions, check out the Getting Started guide here. Authentication The B2 Native API uses application keys to authenticate requests. Please refer to our guide on creating and using application keys for more information. API Base URL The base URL that you will use for most of the B2 Native API operations is returned by the b2_authorize_account call. The base URL looks similar to https://apiNNN.backblazeb2.com with NNN being the cluster number containing your account. For information about constructing the API URL, see Call the B2 Native API. Request and Response Formats The following request and response values are possible using the B2 Native API. Status Codes For all calls to the B2 Native API, the HTTP status code that is returned indicates success or failure. Unsuccessful calls return a JSON error structure in the body of the response that includes the status: a "code" that is a short string and a "message" that is intended only for humans. A status of 200 (OK) means success, and 206 (Partial Content) means success when downloading using the Range header. Any code in the 400 or 500 range is a failure. At present, the API does not use redirects (status codes in the 300 range). Error Structure Failures to connect to the Backblaze B2 Cloud Storage servers and networking problems in general can cause errors, which are reported in a standard format. Any code other than 200 is an error and the response contains a JSON error structure indicating what went wrong. The documentation for each API includes information on the specific errors that are returned for that API; the general classes of errors are as follows: HTTP Status Codes The general classes of errors are included in the following table: 200 The request was successful, and the response contains the JSON structure described in the page for the call. 400 BAD REQUEST There is a problem with a passed in request parameters - the JSON error structure returned will contain an error code of bad_request and a human-readable error message describing the problem. 401 UNAUTHORIZED When calling b2_authorize_account, this means that there was something wrong with the applicationKeyId or with the application key that was provided. The code unauthorized means that the application key is bad. The code unsupported means that the application key is only valid in a later version of the API. When uploading data using b2_upload_file or b2_upload_part, this can mean a variety of things. Try calling b2_get_upload_url or b2_get_upload_part_url again to get a new upload target and auth token. That call will either work or provide a meaningful error code. For all other API calls, the code returned tells you what to do. The code unauthorized means that the auth token is valid, but does not allow you to make this call with these parameters. When the code is either bad_auth_token or expired_auth_token you should call b2_authorize_account again to get a new auth token. 403 FORBIDDEN You have a reached a storage cap limit, or account access may be impacted in some other way; see the human-readable message. 408 REQUEST TIMEOUT The service timed out trying to read your request. 429 TOO MANY REQUESTS B2 may limit API requests on a per-account basis. 500 INTERNAL ERROR An unexpected error has occurred. 503 SERVICE UNAVAILABLE The service is temporarily unavailable. The human-readable message identifies the nature of the issue, in general we recommend retrying with an exponential backoff between retries in response to this error. For more detailed information on handling errors, see the Integration Checklist. JSON Error Structure status The numeric HTTP status code. Always matches the status in the HTTP response. code A single-identifier code that identifies the error. message A human-readable message, in English, indicating what went wrong. The following example shows a JSON error response: { "status" : 400, "code" : "invalid_bucket_name", "message" : "bucket name is too long" } JSON API Versions The current version is v3. Please refer to API Versions for more detailed information about API version history, including breaking changes and compatibility notes. IPv6 Support IPv6 is currently only supported for use with the Backblaze S3-compatible API. b2_authorize_account Get /b2api/v3/b2_authorize_account Returns an authorization token This operation returns an authorization token and base URL for subsequent API calls. You can use either the master application key or a normal application key. NOTE: The account ID can be used in place of the master application key ID. You'll find the master application key in the Backblaze web UI. When using the master application key, use your "master application key ID" and the "application key" you got from the site. Master Application Key: This is the first key you have access to. It is available in the Backblaze web UI. This key has all capabilities, access to all buckets, and has no file prefix restrictions or expiration. Application Key(s) [non-master]: These are other keys created by you that can be limited to a specific bucket, a bucket with a specific file prefix, or all buckets with a specific file prefix, have limited read/write access, and can be set to expire. Normal application keys come from the b2_create_key call. When using one of them, the "application key ID" and "application key" are returned after creating the key. API Versions v3 b2_authorize_account (September 23, 2021) b2_authorize_account now returns a data structure that groups the information you need by API suite. For each suite enabled, it provides the information you need to call those APIs. v2 Return bucket name (Sept 13, 2018) When using an application key with a bucket restriction, the name of the bucket is now returned. Header parameters Authorization string Required An HTTP basic auth value constructed as follows: The application key id and application key are combined into a string in the format "applicationKeyId:applicationKey". The combined string is Base64 encoded. "Basic" is put before the encoded string. Responses 200 The request succeeded. application/json Example Collapse all object accountId string The identifier for the account. Example ACCOUNT_ID apiInfo object A data structure that groups the information you need by API suite. groupsApi object A data structure that contains the information you need for the Partner API. storageApi object A data structure that contains the information you need for the B2 Native API. authorizationToken string An authorization token to use with all calls, other than b2_authorize_account, that need an Authorization header. This authorization token is valid for at most 24 hours. Example AUTHORIZATION_TOKEN applicationKeyExpirationTimestamp integer Expiration timestamp for the application key. Example null b2_upload_file Post /b2api/v3/b2_upload_file Uploads one file and returns its unique file ID Warning Do not include Protected Health Information (PHI) or Personally Identifiable Information (PII) in bucket names; object, file, or folder names; or other metadata. This metadata is not encrypted in a way that meets Health Insurance Portability and Accountability Act (HIPAA) protection requirements for PHI/PII data, and it is not generally encrypted in client-side encryption architectures. Request The upload request is a POST. The file name and other parameters are in the request headers, and the file to be uploaded is the request body. URL Path Use the b2_get_upload_url operation to get a URL you can use to upload files. The URL it returns will contain your bucket ID and the upload destination, and will look something like this: https://pod-000-1007-13.backblaze.com/b2api/v3/b2_upload_file/4a48fe8875c6214145260818/c001_v0001007_t0042 The following HTTP headers must not be included in the b2_upload_file request: Content-Disposition Content-Encoding Content-Language Content-Location Content-Range Expires The file name and file info must fit within a 7,000 byte limit. For files that are uploaded with Server-Side Encryption and/or to Object Lock-enabled buckets, the size limit is reduced to 2,048 bytes. See Files for further details about HTTP header size limit. Request HTTP Message Body Parameters There are no JSON parameters allowed. The file to be uploaded is the message body and is not encoded in any way. It is not URL encoded. It is not MIME encoded. NOTE: You must set the Content-Length HTTP header when using either b2_upload_file or b2_upload_part. Chunked transfer encoding, which allows the Content-Length header to be omitted, is not supported. Header parameters Authorization string Required An upload authorization token obtained from b2_get_upload_url. X-Bz-File-Name string Required The name of the file, in percent-encoded UTF-8. For example, spaces should be replaced with %20. For more information, see Files for requirements on file names and String Encoding for how to encode strings. Content-Type string Required The MIME type of the content of the file, which will be returned in the Content-Type header when downloading the file. Use the Content-Type b2/x-auto to automatically set the stored Content-Type post upload. In the case where a file extension is absent or the lookup fails, the Content-Type is set to application/octet-stream. The Content-Type mappings can be perused here. Content-Length integer Required The number of bytes in the file being uploaded. Note: Chunked transfer encoding, which allows the Content-Length header to be omitted, is not supported. When sending the SHA1 checksum at the end, the Content-Length should be set to the size of the file plus the 40 bytes of hex checksum. X-Bz-Content-Sha1 string Required The SHA1 checksum of the content of the file. B2 will check this when the file is uploaded, to make sure that the file arrived correctly. It will be returned in the X-Bz-Content-Sha1 header when the file is downloaded. You may optionally provide the SHA1 at the end of the upload. See the section on Uploading. X-Bz-Info-src_last_modified_millis string If the original source of the file being uploaded has a last modified time concept, Backblaze recommends using this spelling of one of your X-Bz-Info-* headers (see below). Using a standard spelling allows different B2 clients and the B2 web user interface to interoperate correctly. The value should be a base 10 number which represents a UTC time when the original source file was last modified. It is a base 10 number of milliseconds since midnight, January 1, 1970 UTC. This fits in a 64 bit integer such as the type "long" in the programming language Java. It is intended to be compatible with Java's time long. For example, it can be passed directly into the Java call Date.setTime(long time). X-Bz-Info-b2-content-disposition string If this is present, B2 will use it as the value of the 'Content-Disposition' header when the file is downloaded (unless it's overridden by a value given in the download request). 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. X-Bz-Info-b2-content-language string If this is present, B2 will use it as the value of the 'Content-Language' header when the file is downloaded (unless it's overridden by a value given in the download request). 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 header. X-Bz-Info-b2-expires string If this is present, B2 will use it as the value of the 'Expires' header when the file is downloaded (unless it's overridden by a value given in the download request). 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 header. X-Bz-Info-b2-cache-control string If this is present, B2 will use it as the value of the 'Cache-Control' header when the file is downloaded (unless it's overridden by a value given in the download request), and overriding the value defined at the bucket level. 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-cache-control header. Instead, it (or the value specified in a request) will be in the Cache-Control header. X-Bz-Info-b2-content-encoding string If this is present, B2 will use it as the value of the 'Content-Encoding' header when the file is downloaded (unless it's overridden by a value given in the download request). 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 header. X-Bz-Info-* string The * part of the header name is replaced with the name of a custom field in the file information stored with the file, and the value is an arbitrary UTF-8 string, percent-encoded. The same info headers sent with the upload will be returned with the download. The header name is case insensitive. X-Bz-Custom-Upload-Timestamp string To enable the Custom Upload Timestamp feature on your account, please contact support and provide the start and end dates for your migration. If this is present, B2 will use it as the value of the upload timestamp. The value should be a base 10 number that represents a UTC time when the original source file was uploaded. It is a base 10 number of milliseconds since midnight, January 1st, 1970 UTC. This fits in a 64-bit integer, such as the type long in Java, and so it can be passed directly into the Java call Date.setTime(long time). The value must not use a date that is set to a time in the future. Note: The timestamp should not interfere with the bucket lifecycle rules. For example, if the timestamp created during upload is older than the time specified in the daysFromUploadingToHiding lifecycle rules field, the upload will result in a 400 error. A conflict between the timestamp and a lifecycle rule, such as daysFromHidingToDeleted, may also result in a file being deleted as soon as it is uploaded. X-Bz-File-Legal-Hold string If this is present, specifies the Object Lock legal hold status for the file. Valid values for this header are on and off. Setting the value requires the writeFileLegalHolds capability and that the bucket is Object Lock-enabled. X-Bz-File-Retention-Mode string If this is present, specifies the Object Lock retention mode for the file. Valid values for this header are governance and compliance. Setting the value requires the writeFileRetentions capability and that the bucket is Object Lock-enabled. If this header is present, then a valid X-Bz-File-Retention-Retain-Until-Timestamp header must be present as well. X-Bz-File-Retention-Retain-Until-Timestamp integer If this is present, specifies a Object Lock retention timestamp in the future, after which the intended Object Lock will expire. This header value must be specified as a base 10 number of milliseconds since midnight, January 1, 1970 UTC. Setting the value requires the writeFileRetentions capability and that the bucket is Object Lock-enabled. If this header is present, then a valid X-Bz-File-Retention-Mode header must be present as well. X-Bz-Server-Side-Encryption string If this is present, B2 will encrypt the uploaded data before storing the file using Server-Side Encryption with Backblaze-Managed Keys (SSE-B2) with the algorithm specified in this header. Currently, the only supported value for this header is AES256. This header must not be present if SSE-C headers (X-Bz-Server-Side-Encryption-Customer-*, see below) are included with this request, and vice versa. X-Bz-Server-Side-Encryption-Customer-Algorithm string If this is present, B2 will encrypt the uploaded data before storing the file using Server-Side Encryption with Customer-Managed Keys (SSE-C) with the algorithm specified in this header. Currently, the only supported value for this header is AES256. X-Bz-Server-Side-Encryption-Customer-Key string If this is present, it specifies the base64-encoded encryption key for Backblaze B2 to use in encrypting data with Server-Side Encryption with Customer-Managed Keys (SSE-C). The value of the header is used to store the file and then is immediately discarded. The key must be appropriate for use with the algorithm specified in the X-Bz-Server-Side-Encryption-Customer-Algorithm header. X-Bz-Server-Side-Encryption-Customer-Key-Md5 string If this is present, it specifies the base64-encoded 128-bit MD5 digest of the encryption key to be used with Server-Side Encryption with Customer-Managed Keys (SSE-C). Backblaze B2 uses this header to verify that the encryption key was transmitted correctly. 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. application/json Collapse all object accountId string The account that owns the file. Example 12f634bf3cbz action string One of "start", "upload", "hide", "folder", or other values added in the future. "upload" means a file that was uploaded to B2 Cloud Storage. "start" means that a large file has been started, but not finished or canceled. "hide" means a file version marking the file as hidden, so that it will not show up in b2_list_file_names. "folder" is used to indicate a virtual folder when listing files. Example start bucketId string The bucket that the file is in. Example 4a48fe8875c6214145260818 contentLength string The number of bytes stored in the file. Only useful when the action is "upload". Always 0 when the action is "start", "hide", or "folder". Example 46 contentSha1 string The SHA1 of the bytes stored in the file as a 40-digit hex string. Large files do not have SHA1 checksums, and the value is "none". The value is null when the action is "hide" or "folder" Example bae5ed658ab3546aee12f23f36392f35dba1ebdd contentMd5 string The MD5 of the bytes stored in the file as a 32-digit hex string. Not all files have an MD5 checksum, so this field is optional, and set to null for files that do not have one. Large files do not have MD5 checksums, and the value is null. The value is also null when the action is "hide" or "folder". Example dc724af18fbdd4e59189f5fe768a5f8311527050 contentType string When the action is "upload" or "start", the MIME type of the file, as specified when the file was uploaded. For "hide" action, always "application/x-bz-hide-marker". For "folder" action, always null. Example text/plain fileId string The unique identifier for this version of this file. Used with b2_get_file_info, b2_download_file_by_id, and b2_delete_file_version. The value is null when for action "folder". Example 4_h4a48fe8875c6214145260818_f000000000000472a_d20140104_m032022_c001_v0000123_t0104 fileInfo object The custom information that was uploaded with the file. This is a JSON object, holding the name/value pairs that were uploaded with the file. Example { "author": "unknown" } fileName string The name of this file, which can be used with b2_download_file_by_name. Example typing_test.txt fileRetention object The Object Lock retention settings for this file, if any. This field is filtered based on application key capabilities; the readFileRetentions capability is required to access the value. See Object Lock for more details on response structure. This field is omitted when the action is "hide" or "folder". Example { "isClientAuthorizedToRead": true, "value": { "mode": null, "retainUntilTimestamp": null } } legalHold object The Object Lock legal hold status for this file, if any. This field is filtered based on application key capabilities; the readFileLegalHolds capability is required to access the value. See Object Lock for more details on response structure. This field is omitted when the action is "hide" or "folder". Example { "isClientAuthorizedToRead": true, "value": null } replicationStatus string The Replication Status for this file, if any. This will show either PENDING, COMPLETED, FAILED, or REPLICA For details see Cloud Replication. This field is omitted when the file is not part of a replication rule. Example PENDING serverSideEncryption object When the file is encrypted with Server-Side Encryption, the mode ("SSE-B2" or "SSE-C") and algorithm used to encrypt the data. If the file is not encrypted with Server-Side Encryption, then both mode and algorithm will be null. This field is omitted when the action is "hide" or "folder". Example { "algorithm": "AES256", "mode": "SSE-B2" } uploadTimestamp integer This is a UTC time when this file was uploaded. It is a base 10 number of milliseconds since midnight, January 1, 1970 UTC. This fits in a 64 bit integer such as the type "long" in the programming language Java. It is intended to be compatible with Java's time long. For example, it can be passed directly into the java call Date.setTime(long time). Always 0 when the action is "folder". Example 1559585435000 b2_get_file_info Get /b2api/v3/b2_get_file_info 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. Gets information about a file This will return an error if called on a non-existent file ID or if called on an unfinished large 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 Required An account authorization token, obtained from b2_authorize_account. The token must have the readFiles capability. Query parameters fileId string Required The ID of the file, as returned by b2_upload_file, b2_hide_file, b2_list_file_names, or b2_list_file_versions. 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. application/json Collapse all object accountId string The account that owns the file. Example ACCOUNT_ID action string One of "start", "upload", "hide", "folder", or other values added in the future. "upload" means a file that was uploaded to B2 Cloud Storage. "start" means that a large file has been started, but not finished or canceled. "hide" means a file version marking the file as hidden, so that it will not show up in b2_list_file_names. "folder" is used to indicate a virtual folder when listing files. Example start bucketId string The identifier for the bucket. Example e73ede9c9c8412db49f60715 contentLength integer The number of bytes stored in the file. Only useful when the action is "upload". Always 0 when the action is "start", "hide", or "folder". Example 122573 contentSha1 string The SHA1 of the bytes stored in the file as a 40-digit hex string. Large files do not have SHA1 checksums, and the value is "none". The value is null when the action is "hide" or "folder". Example a01a21253a07fb08a354acd30f3a6f32abb76821 contentMd5 string The MD5 of the bytes stored in the file as a 32-digit hex string. Not all files have an MD5 checksum, so this field is optional, and set to null for files that do not have one. Large files do not have MD5 checksums, and the value is null. The value is also null when the action is "hide" or "folder". Example 142be8357f26eda2ec6775cce257753b contentType string When the action is "upload" or "start", the MIME type of the file, as specified when the file was uploaded. For "hide" action, always "application/x-bz-hide-marker". For "folder" action, always null. Example image/jpeg fileId string The unique identifier for this version of this file. Used with b2_get_file_info, b2_download_file_by_id, and b2_delete_file_version. The value is null when for action "folder". Example 4_ze73ede9c9c8412db49f60715_f100b4e93fbae6252_d20150824_m224353_c900_v8881000_t0001 fileInfo object The custom information that was uploaded with the file. This is a JSON object, holding the name/value pairs that were uploaded with the file. Example { "src_last_modified_millis": "1535629029000" } fileName string The name of this file, which can be used with b2_download_file_by_name. Example akitty.jpg fileRetention object The Object Lock retention settings for this file, if any. This field is filtered based on application key capabilities; the readFileRetentions capability is required to access the value. See Object Lock for more details on response structure. This field is omitted when the action is "hide" or "folder". Example { "isClientAuthorizedToRead": true, "value": { "mode": null, "retainUntilTimestamp": null } } legalHold object The Object Lock legal hold status for this file, if any. This field is filtered based on application key capabilities; the readFileLegalHolds capability is required to access the value. See Object Lock for more details on response structure. This field is omitted when the action is "hide" or "folder". Example { "isClientAuthorizedToRead": true, "value": null } replicationStatus string The Replication Status for this file, if any. This will show either PENDING, COMPLETED, FAILED, or REPLICA For details see Cloud Replication. This field is omitted when the file is not part of a replication rule. Example PENDING serverSideEncryption object When the file is encrypted with Server-Side Encryption, the mode ("SSE-B2" or "SSE-C") and algorithm used to encrypt the data. If the file is not encrypted with Server-Side Encryption, then both mode and algorithm will be null. This field is omitted when the action is "hide" or "folder". Example { "algorithm": "AES256", "mode": "SSE-B2" } uploadTimestamp integer This is a UTC time when this file was uploaded. It is a base 10 number of milliseconds since midnight, January 1, 1970 UTC. This fits in a 64 bit integer such as the type "long" in the programming language Java. It is intended to be compatible with Java's time long. For example, it can be passed directly into the java call Date.setTime(long time). Always 0 when the action is "folder". Example 1536964279000