Uploadcare Upload API Reference
Documentation Powered by ReDoc

Upload API Reference (2022-04-20)

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: 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).

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.

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 -F "UPLOADCARE_PUB_KEY=demopublickey" -F "file=@sample-image.jpeg" "https://upload.uploadcare.com/base/"
Request Body schema: multipart/form-data
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:

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

Note: When developing an API client, we recommend to set the value to auto. The project-wide setting is enabled by default, so if you set the parameter to auto, all the files uploaded via the Upload API will be marked as stored at first as well. You can still delete the files using our Dashboard or by performing a REST API call afterwards.

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

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

expire
number

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

Responses

Request samples

Content type
multipart/form-data
Example
one-file
one-file
two-files
{
  "UPLOADCARE_PUB_KEY": "demopublickey",
  "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.

Note: Multipart Uploads support files larger than 10 megabytes only.

Request Body schema: multipart/form-data
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:

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

Note: When developing an API client, we recommend to set the value to auto. The project-wide setting is enabled by default, so if you set the parameter to auto, all the files uploaded via the Upload API will be marked as stored at first as well. You can still delete the files using our Dashboard or by performing a REST API call afterwards.

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 [ 1 .. 512 ] characters

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

signature
string

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

expire
number

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

Responses

Request samples

Content type
multipart/form-data
{
  "UPLOADCARE_PUB_KEY": "demopublickey",
  "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 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

Responses

Request samples

Content type
application/octet-stream
Chunk of the uploaded file's content.

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

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": "demopublickey",
  "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, 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.

Request Body schema: multipart/form-data
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:

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

Note: When developing an API client, we recommend to set the value to auto. The project-wide setting is enabled by default, so if you set the parameter to auto, all the files uploaded via the Upload API will be marked as stored at first as well. You can still delete the files using our Dashboard or by performing a REST API call afterwards.

filename