Upload API Reference (2015-02-12)

Download OpenAPI specification:Download

API support: help@uploadcare.com

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

The Upload API root is https://upload.uploadcare.com/. All URLs MUST end with a forward slash /.

Once uploaded, your files become available via our CDN.

Every uploaded file is temporary by nature and subject to be deleted within a 24-hour period. Store file to make it permanent.

For each new Uploadcare project, auto-store is on by default. You can turn it off and store files manually:

Check out our API clients that cover most of the popular programming languages and frameworks.

Upload

Direct uploads

Direct uploads comply with the RFC 7578 standard and work by making POST requests via HTTPS. It support files smaller than 100MB only. If you want to upload larger files, use Multipart Uploads.

Request Body schema: multipart/form-data
file
required
Array of strings <binary>

Files

UPLOADCARE_PUB_KEY
required
string

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

UPLOADCARE_STORE
string
Default: "0"
Enum: "0" "1" "auto"

Sets the file storing behavior. If nothing is sent, 0 is used. When developing an API client, we recommend to send auto according to the principle of least surprise.

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project Secret key and it should be generated on your back end. See Secure Uploads for details.

expire
number

expire sets the time during which your signature is valid. It's a UNIX timestamp. See Secure Uploads for details.

Responses

200

Uploaded file UUID.

400

Request parameter validation errors.

403

These are the common errors you can get by the HTTP 403 response code.

413

Direct uploads support files smaller than 100MB only.

429

Request was throttled.

post/base/

Production Server

https://upload.uploadcare.com/base/

Request samples

Content type
multipart/form-data
Example
Copy
{
  "UPLOADCARE_PUB_KEY": "demopublickey",
  "UPLOADCARE_STORE": "auto",
  "my_file.jpg": "@my_file.jpg"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "file": "17be4678-dab7-4bc7-8753-28914a22960a"
}

Start multipart upload

Multipart Uploads are useful for files larger than 100MB or if you want explicitly use accelerated uploads. Your file will go straight to AWS S3 bypassing our upload instances. Therefore, it'll quickly become available for further use. A minimum file size to use with Multipart Uploads is 10MB.

Request Body schema: multipart/form-data
filename
required
string

An original filename

size
required
integer

Precise file size in bytes. Should not exceed your project file size cap.

content_type
required
string

A file MIME-type.

UPLOADCARE_STORE
string
Default: "0"
Enum: "0" "1" "auto"

Sets the file storing behavior. If nothing is sent, 0 is used. When developing an API client, we recommend to send auto according to the principle of least surprise.

UPLOADCARE_PUB_KEY
required
string

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

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project Secret key and it should be generated on your back end. See Secure Uploads for details.

expire
number

expire sets the time during which your signature is valid. It's a UNIX timestamp. See Secure Uploads for details.

Responses

200

Multipart upload start response.

400

Request parameter validation errors.

403

These are the common errors you can get by the HTTP 403 response code.

429

Request was throttled.

post/multipart/start/

Production Server

https://upload.uploadcare.com/multipart/start/

Request samples

Content type
multipart/form-data
Copy
{
  "UPLOADCARE_PUB_KEY": "demopublickey",
  "filename": "myfile.mp4",
  "size": 27796904,
  "content_type": "video/mp4",
  "UPLOADCARE_STORE": "auto"
}

Response samples

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

Uploading individual file parts

The second phase is about uploading file parts to specified URLs. Each uploaded part should be 5MB (5242880 bytes) in size except for the last one that can be smaller. You can upload file parts in parallel provided that the byte order stays unchanged. You MUST define the Content-Type header for your data.

Request Body schema: application/octet-stream
put<presigned-url-x>

Production Server

https://upload.uploadcare.com<presigned-url-x>

Request samples

Content type
application/octet-stream
Copy
RAW document part data

Complete multipart upload

Complete multipart upload transaction when all file parts are uploaded.

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

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

uuid
required
string <uuid>

Uploaded file UUID from multipart upload start response.

Responses

200

Response contains a JSON holding your uploaded file information.

400

Request parameter validation errors.

403

These are the common errors you can get by the HTTP 403 response code.

404

File with specified UUID not found.

post/multipart/complete/

Production Server

https://upload.uploadcare.com/multipart/complete/

Request samples

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "is_stored": true,
  • "done": 2667636,
  • "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "total": 2667636,
  • "size": 2667636,
  • "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "is_image": true,
  • "filename": "IMG_0412.JPG",
  • "video_info": null,
  • "is_ready": true,
  • "original_filename": "IMG_0412.JPG",
  • "image_info":
    {
    },
  • "mime_type": "image/jpeg"
}

Upload files from URLs

"Uploadcare allows fetching files from their URLs.

Such requests return a JSON dictionary with a token that can be further used to check upload statuses for your files. Those tokens are not file UUIDs and cannot be used to address files directly. The actual file UUIDs are returned by the /status/ endpoint.

You can upload some files via /from_url/ more than once. Recurrent Uploads mechanism saves URLs that have already been used with /from_url/. When you start getting data from such a URL, you immediately receive an existing UUID along with related data from your project without having to wait for an actual download. Recurrent Uploads operate within a scope of your Uploadcare project identified by its Public key. To activate the Recurrent Uploads feature, use check_URL_duplicates and save_URL_duplicates.

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

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

source_url
required
string <uri>

Defines your source file URL, which should be a public HTTP or HTTPS link.

store
string
Default: "0"
Enum: "0" "1" "auto"

Sets the file storing behavior. If nothing is sent, 0 is used. When developing an API client, we recommend to send auto according to the principle of least surprise.

filename
string

Sets the name for a file uploaded from URL. If not defined, the filename is obtained from either response headers or a source URL. A filename will be sanitized to the valid symbols: abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789._.

check_URL_duplicates
string
Enum: "0" "1"

Runs the duplicate check and provides the immediate-download behavior.

save_URL_duplicates
string
Enum: "0" "1"

Provides the save/update URL behavior. The parameter can be of help if a source_url is used more than once. If you don’t explicitly define it, its value is set to the value of check_URL_duplicates by default.

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project Secret key and it should be generated on your back end. See Secure Uploads for details.

expire
number

expire sets the time during which your signature is valid. It's a UNIX timestamp. See Secure Uploads for details.

Responses

200

Response structure depends on the type field of a response's JSON.

400

Request parameters validation errors.

403

Common errors for HTTP 403 response code.

429

Request was throttled.

post/from_url/

Production Server

https://upload.uploadcare.com/from_url/

Request samples

Content type
multipart/form-data
Copy
{
  "pub_key": "demopublickey",
  "source_url": "https://bit.ly/2LJ2xOf"
}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "type": "file_info",
  • "is_stored": true,
  • "done": 2667636,
  • "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "total": 2667636,
  • "size": 2667636,
  • "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "is_image": true,
  • "filename": "IMG_0412.JPG",
  • "video_info": null,
  • "is_ready": true,
  • "original_filename": "IMG_0412.JPG",
  • "image_info":
    {
    },
  • "mime_type": "image/jpeg"
}

Check the status of a file uploaded from URL

This method handles file tokens you get when using the /from_url/ method.

query Parameters
token
required
string <uuid>
Example: token=945ebb27-1fd6-46c6-a859-b9893712d650

Sets a token returned by the /from_url/ method. This identifies the upload.

Responses

200

If everything is OK and the status is success, it returns a JSON dictionary holding an uploaded file info. Here's a list of possible upload statuses: unknown, waiting, progress, error, success.

400

token is required.

get/from_url/status/

Production Server

https://upload.uploadcare.com/from_url/status/

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "status": "progress",
  • "done": 100,
  • "total": 150
}

File info

Returns a JSON dictionary holding your file info.

query Parameters
pub_key
required
string
Example: pub_key=demopublickey

A 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 UUID.

Responses

200

Uploaded file info JSON.

400

file_id is required.

403

Common errors for HTTP 403 response code.

404

file_id is invalid.

get/info/

Production Server

https://upload.uploadcare.com/info/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "is_stored": true,
  • "done": 2667636,
  • "file_id": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "total": 2667636,
  • "size": 2667636,
  • "uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb",
  • "is_image": true,
  • "filename": "IMG_0412.JPG",
  • "video_info": null,
  • "is_ready": true,
  • "original_filename": "IMG_0412.JPG",
  • "image_info":
    {
    },
  • "mime_type": "image/jpeg"
}

Groups