Uploadcare Upload API Reference
API docs by Redocly

Upload API Reference (2024-02-12)

Download OpenAPI specification:Download

API support: help@uploadcare.com

Summary

Upload API provides several ways of uploading files to Uploadcare servers in a secure and reliable way.

API endpoints

Upload API's root is located at https://upload.uploadcare.com/. Note: All API endpoints end with a forward slash /. Please do not forget to include it.

API clients

Please checkout API clients page for a list of official and third party Upload API clients.

File storage

Every uploaded file is temporary by nature and subject to be deleted within a 24-hour period. Mark the file as stored to make it permanent:

Note: UPLOADCARE_STORE=auto parameter delegates the choice of the file storing behavior to a project auto-store setting (which is enabled by default).

File delivery

Once uploaded, your files become available via our CDN. The CDN includes on the fly image processing features and can work as a proxy. Please check the referenced page to learn more.

Integrations

You don't have to code most of the low-level API interactions. We have high-level libraries for all popular platforms:

In this API reference, you will see request examples in different languages. Keep in mind that running sample queries requires our libraries to be installed and initialized.

Upload

Direct uploads

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.

Note: Direct file uploads support files smaller than 100 megabytes only. If you would like to upload larger files, please use Multipart Uploads instead.

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 file=@"my file.jpeg"
Request Body schema: multipart/form-data
required
UPLOADCARE_PUB_KEY
required
string (projectPublicKeyType)

Public key identifying an Uploadcare project your uploads will go to.

UPLOADCARE_STORE
string (storeType)
Default: "auto"
Enum: "0" "1" "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.

{filename}
required
Array of strings <binary> [ items <binary > ]

File's content

metadata[{key}]
string (metadataValue) [ 1 .. 512 ] characters

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

signature
string (signatureType)

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.

expire
number (expireType)

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.

Responses

Request samples

Content type
multipart/form-data
Example
{
  "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY",
  "UPLOADCARE_STORE": "auto",
  "my_file.jpg": "@my_file.jpg",
  "metadata[subsystem]": "uploader",
  "metadata[pet]": "cat"
}

Response samples

Content type
application/json
{
  • "my_file.jpg": "17be4678-dab7-4bc7-8753-28914a22960a"
}

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.

Request Body schema: multipart/form-data
UPLOADCARE_PUB_KEY
required
string (projectPublicKeyType)

Public key identifying an Uploadcare project your uploads will go to.

UPLOADCARE_STORE
string (storeType)
Default: "auto"
Enum: "0" "1" "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.

filename
required
string

Original file name of the uploaded file

size
required
integer

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

part_size
integer [ 5242880 .. 5368709120 ]
Default: 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_type
required
string

File's MIME-type.

metadata[{key}]
string (metadataValue) [ 1 .. 512 ] characters

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

signature
string (signatureType)

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.

expire
number (expireType)

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.

Responses

Request samples

Content type
multipart/form-data
{
  "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY",
  "UPLOADCARE_STORE": "auto",
  "filename": "myfile.mp4",
  "size": 27796904,
  "content_type": "video/mp4",
  "metadata[subsystem]": "uploader",
  "metadata[pet]": "cat"
}

Response samples

Content type
application/json
{
  • "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841",
  • "parts": [
    ]
}

Upload individual file parts

The second phase is about uploading the file parts to the presigned upload URLs returned from the /multipart/start/ endpoint.

Each uploaded part should be at least 5 MiB (5242880 bytes) in size except for the last one, which can be smaller. You can upload the file parts in parallel provided that the byte order stays unchanged.

Note: You MUST define Content-Type header for your data.

Request Body schema: application/octet-stream
object

Part of the uploaded file.

Don't include https://upload.uploadcare.com/ in this request:

curl -X PUT "<presigned-url-x>" -H "Content-Type: application/octet-stream" --data <data-part>

Responses

Request samples 

import { multipartUpload } from '@uploadcare/upload-client'

// partData is a chunk of the uploaded file's content
// must be `Blob` or `File` or `Buffer`
const result = await multipartUpload(
  partData,
  '<presigned-url-x>'
)

Complete multipart upload

Once all the file parts have been uploaded successfully, complete the upload session to assemble all the file parts into a single resulting file.

Request Body schema: multipart/form-data
UPLOADCARE_PUB_KEY
required
string (projectPublicKeyType)

Public key identifying an Uploadcare project your uploads will go to.

uuid
required
string <uuid>

File's UUID from the /multipart/start/ endpoint.

Responses

Request samples

Content type
multipart/form-data
{
  "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY",
  "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841"
}

Response samples

Content type
application/json
{
  • "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "size": 2667636,
  • "total": 2667636,
  • "done": 2667636,
  • "original_filename": "IMG-0412_123.JPG",
  • "filename": "IMG0412_123.JPG",
  • "mime_type": "image/jpeg",
  • "image_info": {
    },
  • "video_info": null,
  • "content_info": {
    },
  • "metadata": {
    },
  • "is_image": true,
  • "is_stored": true,
  • "is_ready": true
}

Upload files from URLs

Uploadcare can fetch a file from a publicly available URL and then automatically upload the fetched file to your project.

Upload tokens

Requests to the endpoint return a JSON dictionary with a token that can be further used to check the status of the upload request.

Note: The token is not a file ID and can't be used to address the file directly. The actual file ID should be retrieved by calling the /from_url/status/ endpoint.

Duplicates prevention

By default, every call to the /from_url/ endpoint with the same source_url results in a new upload leading to file duplication.

If you would like Uploadcare to keep track of the requested URLs and avoid the duplicate uploads, pass the save_URL_duplicates and check_URL_duplicates parameters described below.

Request Body schema: multipart/form-data
pub_key
required
string (projectPublicKeyType)

Public key identifying an Uploadcare project your uploads will go to.

source_url
required
string <uri>

Source URL of the file to fetch and upload.

Note: The URL should point to a resource publicly available via HTTP/HTTPS.

store
string (storeType)
Default: "auto"
Enum: "0" "1" "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.

filename
string

Sets the file name of the resource fetched from the source URL. If not defined, the file name is obtained from either HTTP response headers or the source_url's path.

Note: The filename will be sanitized to only contain the following symbols: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._.

check_URL_duplicates
string
Default: "0"
Enum: "0" "1"

If set to "1", enables the source_url duplicates prevention. Specifically, if the source_url had already been fetched and uploaded previously, this request will return information about the already uploaded file.

save_URL_duplicates
string
Enum: "0" "1"

Determines if the requested source_url should be kept in the history of fetched/uploaded URLs. If the value is not defined explicitly, it is set to the value of the check_URL_duplicates parameter.

metadata[{key}]
string (metadataValue) [ 1 .. 512 ] characters

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

signature
string (signatureType)

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.

expire
number (expireType)

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.

Responses

Request samples

Content type
multipart/form-data
{
  "pub_key": "YOUR_PUBLIC_KEY",
  "source_url": "https://source.unsplash.com/featured",
  "metadata[subsystem]": "uploader",
  "metadata[pet]": "cat"
}

Response samples

Content type
application/json
Example
{
  • "type": "token",
  • "token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}

Check the status of a task to fetch/upload a file from a URL

The endpoint notifies about the progress of the task by changing the value of the status field:

  • the field is set to waiting initially
  • once the system starts processing the request, the field is set to progress
  • if the file is fetched and uploaded successfully, the status field is set to success and the endpoint returns a JSON object holding information about the uploaded file
  • if the system fails to fetch/upload the file, the status field is set to error and the error field is set to the cause of the error.
query Parameters
token
required
string <uuid>
Example: token=945ebb27-1fd6-46c6-a859-b9893712d650

Token returned by the /from_url/ endpoint that identifies a request to fetch/upload a file from a URL.

Responses

Request samples 

import { fromUrlStatus } from '@uploadcare/upload-client'

const result = await fromUrlStatus(
  '945ebb27-1fd6-46c6-a859-b9893712d650',
  {
    publicKey: 'YOUR_PUBLIC_KEY'
  }
)

Response samples

Content type
application/json
Example
{
  • "status": "waiting"
}

Get information about an uploaded file

Returns a JSON object with information about an uploaded file (file size, MIME type, metadata, etc).

query Parameters
pub_key
required
string (projectPublicKeyType)
Example: pub_key=YOUR_PUBLIC_KEY

Public key identifying an Uploadcare project your uploads will go to.

file_id
required
string <uuid>
Example: file_id=67947755-1584-4e3f-902b-d4e2bf76a841

File's unique ID.

Responses

Request samples 

import { info } from '@uploadcare/upload-client'

const result = await info(
  'be3b4d5e-179d-460e-8a5d-69112ac86cbb',
  {
    publicKey: 'YOUR_PUBLIC_KEY'
  }
)

Response samples

Content type
application/json
{
  • "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "size": 2667636,
  • "total": 2667636,
  • "done": 2667636,
  • "original_filename": "IMG-0412_123.JPG",
  • "filename": "IMG0412_123.JPG",
  • "mime_type": "image/jpeg",
  • "image_info": {
    },
  • "video_info": null,
  • "content_info": {
    },
  • "metadata": {
    },
  • "is_image": true,
  • "is_stored": true,
  • "is_ready": true
}

Groups

Create a file group

Create a file group from a set of already uploaded files.

The most common use case for creating a file group is when a user uploads multiple files at once and then wants to display them together.

Note: A group itself and files within it MUST belong to the same project.

Note: Groups are immutable and the only way to add/remove a file to a group is to create a new one.

Request Body schema: multipart/form-data
required
pub_key
required
string (projectPublicKeyType)

Public key identifying an Uploadcare project your uploads will go to.

files[]
required
Array of strings

Set of files you want to add to the group. Each element can be a file UUID with or without the applied image processing operations.

signature
string (signatureType)

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.

expire
number (expireType)

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.

Responses

Request samples

Content type
multipart/form-data
{
  "pub_key": "YOUR_PUBLIC_KEY",
  "files[]": [
    "d6d34fa9-addd-472c-868d-2e5c105f9fcd",
    "b1026315-8116-4632-8364-607e64fca723/-/resize/x800/"
  ]
}

Response samples

Content type
application/json
{
  • "id": "0d712319-b970-4602-850c-bae1ced521a6~1",
  • "datetime_created": "2018-09-12T10:03:38.686710Z",
  • "datetime_stored": null,
  • "files_count": 1,
  • "cdn_url": "https://ucarecdn.com/0d712319-b970-4602-850c-bae1ced521a6~1/",
  • "url": "https://api.uploadcare.com/groups/0d712319-b970-4602-850c-bae1ced521a6~1/",
  • "files": [
    ]
}

Get information about a file group

Returns a JSON object with information about a file group (when the group was created, number of the files in the group, etc).

query Parameters
pub_key
required
string (projectPublicKeyType)
Example: pub_key=YOUR_PUBLIC_KEY

Public key identifying an Uploadcare project your uploads will go to.

group_id
required
string
Example: group_id=d52d7136-a2e5-4338-9f45-affbf83b857d~2

Group's unique ID. Group IDs look like UUID~N, where the ~N part reflects the number of the files in the group.

Responses

Request samples 

import { groupInfo } from '@uploadcare/upload-client'

const result = await groupInfo(
  '0d712319-b970-4602-850c-bae1ced521a6~1',
  {
    publicKey: 'YOUR_PUBLIC_KEY'
  }
)

Response samples

Content type
application/json
{
  • "id": "0d712319-b970-4602-850c-bae1ced521a6~1",
  • "datetime_created": "2018-09-12T10:03:38.686710Z",
  • "datetime_stored": null,
  • "files_count": 1,
  • "cdn_url": "https://ucarecdn.com/0d712319-b970-4602-850c-bae1ced521a6~1/",
  • "url": "https://api.uploadcare.com/groups/0d712319-b970-4602-850c-bae1ced521a6~1/",
  • "files": [
    ]
}

Errors

If the request fails, Upload API returns an error response. Error responses are returned in the form of a JSON object with an error code, an HTTP status code and an error message. The following errors are possible.

Error code HTTP status code Error message
Base upload errors:
AccountBlockedError 403 Account has been blocked.
AccountLimitsExceededError 403 Account has reached its limits.
AccountUnpaidError 403 Account has been blocked for non payment.
AutostoreDisabledError 403 Autostore is disabled.
BaseViewsError 400 Request processing failed.
FileMetadataKeyDuplicatedError 400 File's metadata key `%s` has a duplicate.
FileMetadataKeyEmptyError 400 File's metadata key can not be empty.
FileMetadataKeyForbiddenError 400 File's metadata key `%s` contains symbols not allowed by the metadata key format.
FileMetadataKeyLengthTooBigError 400 Length of file metadata key `%s` can not be more than %d symbols.
FileMetadataKeysNumberTooBigError 400 A file can not have more than %d metadata keys.
FileMetadataValueEmptyError 400 Value of the file metadata key `%s` can not be empty.
FileMetadataValueForbiddenError 400 Value of file metadata key `%s` contains symbols not allowed by the metadata value format.
FileMetadataValueLengthTooBigError 400 Value of file metadata's key `%s` can not be more than %d symbols in length.
FileSizeLimitExceededError 400 File is too large.
MethodNotAllowedError 405 HTTP method %s is not allowed for %s
NullCharactersForbiddenError 400 Null characters are not allowed.
PostRequestParserFailedError 400 HTTP POST request parsing failed.
ProjectPublicKeyInvalidError 403 %s is invalid.
ProjectPublicKeyRemovedError 403 Project %s is marked as removed.
ProjectPublicKeyRequiredError 403 %s is required.
RequestFileNumberLimitExceededError 400 The request contains too many files.
RequestFiledsNumberLimitExceededError 400 The request contains too many HTTP POST fields.
RequestSizeLimitExceededError 413 The size of the request is too large.
RequestThrottledError 429 Request was throttled.
SignatureExpirationError 403 Expired signature.
SignatureExpirationInvalidError 400 `expire` must be a UNIX timestamp.
SignatureExpirationRequiredError 400 `expire` is required.
SignatureInvalidError 403 Invalid signature.
SignatureRequiredError 400 `signature` is required.
UploadAPIError 500 Internal error.
UploadFailedError 403 Upload failed.
FromURL upload errors:
DownloadFileError 500 Failed to download the file.
DownloadFileHTTPClientError 500 HTTP client error: %s.
DownloadFileHTTPNetworkError 500 HTTP network error: %s.
DownloadFileHTTPServerError 500 HTTP server error: %s.
DownloadFileHTTPURLValidationError 500 HTTP URL validation error: %s.
DownloadFileInternalServerError 500 Internal server error.
DownloadFileNotFoundError 500 downloaded file not found.
DownloadFileSizeLimitExceededError 500 Downloaded file is too big: %s > %s.
DownloadFileTaskFailedError 500 download task failed.
DownloadFileTimeLimitExceededError 500 Failed to download the file within the allotted time limit of %s seconds.
DownloadFileValidationFailedError 500 File validation error: %s
File upload errors:
FileIdInvalidError 400 file_id is invalid.
FileIdNotUniqueError 400 File id must be unique.
FileIdRequiredError 400 file_id is required.
FileNotFoundError 404 File is not found.
FileRequiredError 400 There should be a file.
FilesNumberLimitExceededError 400 There are too many files.
FilesRequiredError 400 Request does not contain files.
InternalRequestForbiddenError 403 Forbidden request.
InternalRequestInvalidError 400 Incorrect request.
MultipartFileAlreadyUploadedError 400 File is already uploaded.
MultipartFileCompletionFailedError 400 Can not complete upload. Wrong parts size?
MultipartFileIdRequiredError 400 uuid is required.
MultipartFileNotFoundError 404 File is not found.
MultipartFileSizeLimitExceededError 400 File size exceeds project limit.
MultipartFileSizeTooSmallError 400 File size can not be less than %d bytes. Please use direct upload instead of multipart.
MultipartPartSizeInvalidError 400 Multipart Upload Part Size should be an integer.
MultipartPartSizeTooBigError 400 Multipart Upload Part Size can not be more than %d bytes.
MultipartPartSizeTooSmallError 400 Multipart Upload Part Size can not be less than %d bytes.
MultipartSizeInvalidError 400 size should be integer.
MultipartUploadSizeTooLargeError 400 Uploaded size is more than expected.
MultipartUploadSizeTooSmallError 400 File size mismatch. Not all parts uploaded?
RequestParamRequiredError 400 %s is required.
SourceURLRequiredError 400 source_url is required.
TokenRequiredError 400 token is required.
UUIDInvalidError 400 uuid is invalid.
UploadViewsError 400 Upload request processing failed.
UploadcareFileIdDuplicatedError 400 UPLOADCARE_FILE_ID is duplicated. You are probably a lottery winner.
UploadcareFileIdInvalidError 400 UPLOADCARE_FILE_ID should be a valid UUID.
UploadcareFileIdRequiredError 400 UPLOADCARE_FILE_ID is required.
File group errors:
GroupFileURLParsingFailedError 400 This is not valid file url: %s.
GroupFilesInvalidError 400 No files[N] parameters found.
GroupFilesNotFoundError 400 Some files not found.
GroupIdRequiredError 400 group_id is required.
GroupNotFoundError 404 group_id is invalid.
GroupViewsError 400 Request to group processing failed.
File content validation errors:
SVGValidationFailedError 400 SVG validation failed: %s.
SVGMaliciousContentError 400 SVG contains malicious content: %s.
FileInfectedError 400 The file is infected by %s virus.
FileTypeForbiddenError 400 Uploading of these file types is not allowed.
URL validation errors:
HostnameNotFoundError 400 Host does not exist.
URLBlacklistedError 400 Source is blacklisted.
URLHostMalformedError 400 URL host is malformed.
URLHostPrivateIPForbiddenError 400 Only public IPs are allowed.
URLHostRequiredError 400 No URL host supplied.
URLParsingFailedError 400 Failed to parse URL.
URLRedirectsLimitExceededError 400 Too many redirects.
URLSchemeInvalidError 400 Invalid URL scheme.
URLSchemeRequiredError 400 No URL scheme supplied.
URLValidationError 400 Failed to validate URL.

Other APIs

You can find the complete reference documentation for the REST API here and URL API here.