b2_upload_part
- 11 Sep 2026
- Print
- DarkLight
b2_upload_part
- Updated on 11 Sep 2026
- Print
- DarkLight
Article summary
Did you find this summary helpful?
Thank you for your feedback
Post
/b2api/v4/b2_upload_part
Uploads one part of a large file to B2, using an file ID obtained from b2_start_large_file
NOTE:
The part inherits the encryption selected by b2_start_large_file. No additional SSE-B2 parameter is required.
For more information, see Server-Side Encryption.
Once all of the parts are uploaded, use b2_finish_large_file to make the file available for use.
If you upload the same part number for the same file more than once, both uploads will succeed, and the second upload will overwrite the first.
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.
Use the b2_get_upload_part_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-1016-09.backblaze.com/b2api/v4/b2_upload_part/4_ze73ede9c9c8412db49f60715_f200b4e93fbae6252_d20150824_m224353_c900_v8881000_t0001/0037Some errors returned mean that you must call b2_get_upload_url again to get a new upload URL and authorization token. See Uploading for details.
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.
API Versions
v1: Add uploadTimestamp field (August 30, 2018)
The response now includes the same uploadTimestamp field returned by b2_list_buckets.
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
X-Bz-Part-Number
stringRequired
A number from 1 to 10000. The parts uploaded for one file must have contiguous numbers, starting with 1.
Content-Length
integerRequired
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
stringRequired
The SHA1 checksum of this part of the file. B2 will check this when the part is uploaded, to make sure that the data arrived correctly.
The same SHA1 checksum must be passed to b2_finish_large_file.
You may optionally provide the SHA1 at the end of the upload. See the section on Uploading.
X-Bz-Server-Side-Encryption-Customer-Algorithm
string
This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption algorithm requested via b2_start_large_file.
X-Bz-Server-Side-Encryption-Customer-Key
string
This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption customerKey requested via b2_start_large_file.
X-Bz-Server-Side-Encryption-Customer-Key-Md5
string
This header is required if b2_start_large_file was called with parameters specifying Server-Side Encryption with Customer-Managed Keys (SSE-C), in which case its value must match the serverSideEncryption customerKeyMd5 requested via b2_start_large_file.
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.
object
fileId
string
The file ID for uploading this file.
Example4_ze73ede9c9c8412db49f60715_f200b4e93fbae6252_d20150824_m224353_c900_v8881000_t0001
partNumber
integer
Which part this is.
Example1
contentLength
integer
The number of bytes stored in the part.
Example100000000
contentSha1
string
The SHA1 of the bytes stored in the part.
Example062685a84ab248d2488f02f6b01b948de2514ad8
contentMd5
string
The MD5 of the bytes stored in the part. Not all parts have an MD5 checksum, so this field is optional, and set to null for parts that do not have one.
Example142be8357f26eda2ec6775cce257753b
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": null, "mode": null }
algorithm
string
mode
string
uploadTimestamp
integer
This is a UTC time when this part 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).
Example1559585435000
400
| status | code | description |
|---|---|---|
| 400 | auth_token_limit | The auth token is already being used. For more information, see Uploading in Parallel. |
| 400 | bad_request | The request had the wrong fields or illegal values. The message returned with the error will describe the problem. |
| 400 | bad_bucket_id | The requested bucket ID does not match an existing bucket. |
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
| status | code | description |
|---|---|---|
| 401 | bad_auth_token | The auth token used has expired. Call b2_get_upload_part_url again to get a new one. |
| 401 | expired_auth_token | The auth token used has expired. Call b2_get_upload_part_url again to get a new one. |
| 401 | unauthorized | The 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. |
405
| status | code | description |
|---|---|---|
| 405 | method_not_allowed | only POST is supported |
408
| status | code | description |
|---|---|---|
| 408 | request_timeout | The service timed out reading the uploaded file |
411
| status | code | description |
|---|---|---|
| 411 | length_required | The Content-Length header is missing |
503
| status | code | description |
|---|---|---|
| 503 | service_unavailable | Call b2_get_upload_part_url again to get a new auth token. |
Was this article helpful?