Direct uploads | Uploadcare docs

Direct file uploads comply with the RFC 7578 standard. In other words, you can perform a direct upload by making an HTTP POST request with the Content-Type header set to multipart/form-data. A single request can include multiple files, each under its own form field name. tags and metadata apply identically to every file in the request: there’s no way to assign different values per file in a single call, so send separate requests, or update files individually afterward via the REST API, if you need per-file values.

Note: The combined size of a direct upload request (all files and form fields together) must not exceed 100 megabytes. This is a limit on the whole request, not on each file individually, so uploading several files in one request counts their combined size toward it. If a single file exceeds 100 megabytes, use Multipart Uploads instead.

Note: With signed uploads, the scope value of this endpoint is /base/. A request spends one operation per file of the token’s operations limit.

File upload example with curl:

curl -X POST https://upload.uploadcare.com/base/ \
     -F UPLOADCARE_PUB_KEY="demopublickey" \
     -F UPLOADCARE_STORE="auto" \
     -F "metadata[subsystem]"="uploader" \
     -F "metadata[pet]"="cat" \
     -F "tags"="cat,animal,cute" \
     -F file=@"photo1.jpg" \
     -F file2=@"photo2.jpg"

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 with multiple files.

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:

{filename}filesRequired

File's content

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

The file was uploaded successfully.

Errors

400

Bad Request Error