Skip to main content
When you want to upload a large file, you can split it into smaller parts and upload them using the Upload Part API.

Create upload session

First, . The resulting object defines the size of each part and the number of parts to upload.

Split file

Split the file into parts to be uploaded. If you want to use the command line, use the split command:
For example:
This command divides your file into several files.

Get SHA digest

You can use a SHA-1 or a SHA-512 digest to verify each part. To get the value for the SHA digest, use one of the following OpenSSL commands to encode the file part:
For example:
The result is a base-64 encoded message used to verify the upload. Pass it in the digest header as sha=BASE64_ENCODED_DIGEST for SHA-1, or sha-512=BASE64_ENCODED_DIGEST for SHA-512.

Skip parts Box already stores

When you upload a new version of a file, you can plan the upload session before you upload any parts. Planning is optional, and it tells you which parts Box already stores from the previous version of the file. The plan request needs the SHA-512 hash of each part as a lowercase, 128-character hexadecimal string. To get it, use the following OpenSSL command:
For example:
Send the offset, size, and sha512 of each part to . The response splits the parts into two lists:
  • hits: Parts that Box already stores and has added to the upload session. Don’t upload these parts.
  • misses: Parts that Box doesn’t store. Upload these parts as described in the next section.
You can safely retry a plan request with the same payload. When you , include both the uploaded parts and the hits.
The Box SDKs plan the session for you when you upload a new version with the .

Upload part

Upload the bytes for the part you want to upload, specifying the byte range for the part and the SHA digest to ensure the content is uploaded correctly. If you planned the upload session, only upload the parts listed in misses.

Content range

Each part must match the part size specified in the upload session you created. The last part of the file can be smaller. The Content-Range parameter definition follows this pattern:
When providing the value for Content-Range, remember that:
  • The lower bound of each part’s byte range must be a multiple of the part size.
  • The higher bound must be one less than a multiple of the part size.
For example, if the part size is 8388608, the content range for the first two parts is:

Response

After each upload, the resulting response includes the ID and SHA hashes of the part uploaded.
The response always includes sha512, as a lowercase hexadecimal string. It includes sha1 only if you uploaded the part with a SHA-1 digest.
Keep all the JSON responses from all part uploads, and the hits from the plan response if you planned the session. You need them to .

Range overlap

If a part upload request fails with the error code range_overlaps_existing_part, the application made a mistake in cutting up the file into parts and tried to upload a part into a range that already had content uploaded for it. The application should assume that this last part was not persisted to the session.

Parallel uploads

Although you can upload the parts in parallel, upload them in order as much as possible. Upload parts with a lower byte offset before parts with a higher byte offset. The recommended approach is to upload 3 to 5 parts in parallel from a queue of parts, ordered by byte offset. If a part upload fails, retry it before you upload further parts.
Last modified on November 12, 2026