Download OpenAPI specification:Download
Upload API provides several ways of uploading files to Uploadcare servers in a secure and reliable way.
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.
Please checkout API clients page for a list of official and third party Upload API clients.
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:
UPLOADCARE_STORE
flagNote: UPLOADCARE_STORE=auto
parameter delegates the choice of the
file storing behavior to a project
auto-store
setting (which is enabled by default).
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.
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.
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 -F "UPLOADCARE_PUB_KEY=YOUR_PUBLIC_KEY" -F "my_file.jpg=@my_file.jpg" "https://upload.uploadcare.com/base/"
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:
The default value depends on the user registration date. For all users registered after February 12, 2024 (UTC 13:30), the default value is For users registered before February 12, 2024, the default value is |
{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)
|
expire | number (expireType)
|
{ "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY", "UPLOADCARE_STORE": "auto", "my_file.jpg": "@my_file.jpg", "metadata[subsystem]": "uploader", "metadata[pet]": "cat" }
{- "my_file.jpg": "17be4678-dab7-4bc7-8753-28914a22960a"
}
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:
/multipart/start/
<presigned-url-x>
/multipart/complete/
.Note: Multipart uploads support files larger than 10 megabytes only.
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:
The default value depends on the user registration date. For all users registered after February 12, 2024 (UTC 13:30), the default value is For users registered before February 12, 2024, the default value is |
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 |
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)
|
expire | number (expireType)
|
{ "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY", "UPLOADCARE_STORE": "auto", "filename": "myfile.mp4", "size": 27796904, "content_type": "video/mp4", "metadata[subsystem]": "uploader", "metadata[pet]": "cat" }
{- "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841",
- "parts": [
- "<presigned-url-1>",
- "<presigned-url-2>",
- "<presigned-url-3>",
- "<presigned-url-4>",
- "<presigned-url-5>"
]
}
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.
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>
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>' )
Once all the file parts have been uploaded successfully, complete the upload session to assemble all the file parts into a single resulting file.
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 |
{ "UPLOADCARE_PUB_KEY": "YOUR_PUBLIC_KEY", "uuid": "67947755-1584-4e3f-902b-d4e2bf76a841" }
{- "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": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}, - "video_info": null,
- "content_info": {
- "mime": {
- "mime": "image/jpeg",
- "type": "image",
- "subtype": "jpeg"
}, - "image": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}
}, - "metadata": {
- "subsystem": "uploader",
- "pet": "cat"
}, - "is_image": true,
- "is_stored": true,
- "is_ready": true
}
Uploadcare can fetch a file from a publicly available URL and then automatically upload the fetched file to your project.
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.
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.
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:
The default value depends on the user registration date. For all users registered after February 12, 2024 (UTC 13:30), the default value is For users registered before February 12, 2024, the default value is |
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 Note: The filename will be sanitized to only contain the following symbols:
|
check_URL_duplicates | string Default: "0" Enum: "0" "1" If set to "1", enables the |
save_URL_duplicates | string Enum: "0" "1" Determines if the requested |
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)
|
expire | number (expireType)
|
{ "pub_key": "YOUR_PUBLIC_KEY", "source_url": "https://source.unsplash.com/featured", "metadata[subsystem]": "uploader", "metadata[pet]": "cat" }
{- "type": "token",
- "token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}
The endpoint notifies about the progress of the task by changing the value of the status
field:
waiting
initiallyprogress
status
field is set to success
and the endpoint returns a JSON object holding information about the uploaded filestatus
field is set to error
and
the error
field is set to the cause of the error.token required | string <uuid> Example: token=945ebb27-1fd6-46c6-a859-b9893712d650 Token returned by the |
import { fromUrlStatus } from '@uploadcare/upload-client' const result = await fromUrlStatus( '945ebb27-1fd6-46c6-a859-b9893712d650', { publicKey: 'YOUR_PUBLIC_KEY' } )
{- "status": "waiting"
}
Returns a JSON object with information about an uploaded file (file size, MIME type, metadata, etc).
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. |
import { info } from '@uploadcare/upload-client' const result = await info( 'be3b4d5e-179d-460e-8a5d-69112ac86cbb', { publicKey: 'YOUR_PUBLIC_KEY' } )
{- "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": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}, - "video_info": null,
- "content_info": {
- "mime": {
- "mime": "image/jpeg",
- "type": "image",
- "subtype": "jpeg"
}, - "image": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}
}, - "metadata": {
- "subsystem": "uploader",
- "pet": "cat"
}, - "is_image": true,
- "is_stored": true,
- "is_ready": true
}
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.
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)
|
expire | number (expireType)
|
{ "pub_key": "YOUR_PUBLIC_KEY", "files[]": [ "d6d34fa9-addd-472c-868d-2e5c105f9fcd", "b1026315-8116-4632-8364-607e64fca723/-/resize/x800/" ] }
{- "id": "0d712319-b970-4602-850c-bae1ced521a6~1",
- "datetime_created": "2018-09-12T10:03:38.686710Z",
- "datetime_stored": null,
- "files_count": 1,
- "files": [
- {
- "default_effects": "resize/x800/",
- "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": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}, - "video_info": null,
- "content_info": {
- "mime": {
- "mime": "image/jpeg",
- "type": "image",
- "subtype": "jpeg"
}, - "image": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}
}, - "metadata": {
- "subsystem": "uploader",
- "pet": "cat"
}, - "is_image": true,
- "is_stored": true,
- "is_ready": true
}
]
}
Returns a JSON object with information about a file group (when the group was created, number of the files in the group, etc).
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 |
import { groupInfo } from '@uploadcare/upload-client' const result = await groupInfo( '0d712319-b970-4602-850c-bae1ced521a6~1', { publicKey: 'YOUR_PUBLIC_KEY' } )
{- "id": "0d712319-b970-4602-850c-bae1ced521a6~1",
- "datetime_created": "2018-09-12T10:03:38.686710Z",
- "datetime_stored": null,
- "files_count": 1,
- "files": [
- {
- "default_effects": "resize/x800/",
- "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": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}, - "video_info": null,
- "content_info": {
- "mime": {
- "mime": "image/jpeg",
- "type": "image",
- "subtype": "jpeg"
}, - "image": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "height": 4032,
- "width": 3024,
- "sequence": false,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 72,
- 72
]
}
}, - "metadata": {
- "subsystem": "uploader",
- "pet": "cat"
}, - "is_image": true,
- "is_stored": true,
- "is_ready": true
}
]
}
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. |