Skip to navigation
Upload APIUpload

Start multipart upload

Multipart uploads should be used if you need to upload files larger than 100 megabytes or if you want to explicitly trigger AWS S3 Transfer Acceleration. When you use Multipart Uploads your files go straight to AWS S3 bypassing our upload instances.

To upload large files, 3 requests are sent in sequence:

  1. /multipart/start/
  2. <presigned-url-x>
  3. /multipart/complete/.
Note: Multipart uploads support files larger than 10 megabytes only.
Note: With signed uploads, the scope value of this endpoint is /multipart/start/. A request spends one operation of the token’s operations limit.

Authentication

AuthorizationBearer

Signed uploads with a JSON Web Token (RFC 7519), generated on your backend with the project Secret key and sent in the Authorization header:

Authorization: Bearer <jwt>

The token is checked only when signed uploads are enabled for the project. Signing, claims, scope and operation limits, and error responses are specified in Authentication. The scope value of each endpoint, and how many operations a request spends, is listed in the endpoint description.

Request

This endpoint expects a multipart form.
UPLOADCARE_PUB_KEYstringRequired
Public key identifying an Uploadcare project your uploads will go to.
UPLOADCARE_STOREenumOptionalDefaults to auto

Determines if an uploaded file should be marked as temporary or permanent.

The parameter can have the following values:

  • 0 - do not mark an uploaded file as stored and remove it after 24 hours
  • 1 - mark the uploaded file as stored
  • auto - delegate the choice of the file-storing behavior to a project-wide setting called auto-store.

The default value depends on the user registration date.

For all users registered after February 12, 2024 (UTC 13:30), the default value is auto. File-storing behavior depends entirely on what is set in the storage settings in the Dashboard.

For users registered before February 12, 2024, the default value is 0. To ensure that file storage in the project matches the settings in the Dashboard, change the value to auto.

Allowed values:
filenamestringRequired
Original file name of the uploaded file
sizeintegerRequired

Precise file size of the uploaded file (in bytes). Note: The size should not exceed max file size cap for your project.

part_sizeintegerOptional5242880-5368709120Defaults to 5242880

Multipart Uploads expect that you will split the uploaded file into equally sized parts (except for the last part) and then will upload them to AWS S3 (possibly in parallel). By default, we assume that you will upload the files in 5 megabyte chunks, so we return a list of presigned AWS S3 URLs accordingly. If you intend to upload large files (for example, larger than a gigabyte), we recommend to bump the part size and to pass the expected chunk size to us as a value of the part_size parameter (in bytes).

content_typestringRequired

File’s MIME-type.

metadata[{key}]stringOptional1-512 characters

Arbitrary metadata associated with the file. See docs and REST API for more information.

tagsstringOptional

Comma-separated list of string tags to attach to the uploaded file. Tags are normalized before storage: lowercased, whitespace-stripped, duplicates removed. Each tag may only contain Latin letters, digits, hyphens (-), underscores (_), and dots (.). Maximum 50 tags; each tag must not exceed 100 characters. Invalid tags cause a 400 error and the upload does not proceed.

signaturestringOptional

signature must be sent along with your upload request if you would like to use signed uploads. The signature should be generated on your backend. Note: the process requires knowledge of your Uploadcare Project’s Secret key. See signed uploads for details.

expireintegerOptional

expire must be sent along with your upload request if you would like to use signed uploads. The parameter defines the time during which your signature is valid. It’s a UNIX timestamp. See signed uploads for details.

Response

Multipart upload started successfully.
uuidstringformat: "uuid"
File's UUID.
partslist of strings

Errors

400
Bad Request Error