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: Use of the 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.
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=demopublickey" -F "file=@sample-image.jpeg" "https://upload.uploadcare.com/base/"
UPLOADCARE_PUB_KEY required | string Public key identifying an Uploadcare project your uploads will go to. |
UPLOADCARE_STORE | string Default: "0" Enum: "0" "1" "auto" Determines if an uploaded file should be marked as temporary or permanent. The parameter can have the following values:
Note: When developing an API client, we recommend to set the value to |
filename required | string <binary> File's content |
metadata[{key}] | string [ 1 .. 512 ] characters Arbitrary metadata associated with the file. See REST API v0.7 for more information. |
signature | string
|
expire | number
|
{ "UPLOADCARE_PUB_KEY": "demopublickey", "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.
Note: Multipart Uploads support files larger than 10 megabytes only.
UPLOADCARE_PUB_KEY required | string Public key identifying an Uploadcare project your uploads will go to. |
UPLOADCARE_STORE | string Default: "0" Enum: "0" "1" "auto" Determines if an uploaded file should be marked as temporary or permanent. The parameter can have the following values:
Note: When developing an API client, we recommend to set the value to |
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 [ 1 .. 512 ] characters Arbitrary metadata associated with the file. See REST API v0.7 for more information. |
signature | string
|
expire | number
|
{ "UPLOADCARE_PUB_KEY": "demopublickey", "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 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
Chunk of the uploaded file's content.
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 Public key identifying an Uploadcare project your uploads will go to. |
uuid required | string <uuid> File's UUID from the |
{ "UPLOADCARE_PUB_KEY": "demopublickey", "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, duplicate calls to the /from_url/
endpoint with the same source_url
lead to
duplicate file fetches and uploads.
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 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 Default: "0" Enum: "0" "1" "auto" Determines if an uploaded file should be marked as temporary or permanent. The parameter can have the following values:
Note: When developing an API client, we recommend to set the value to |
filename |