Upload API Reference (2015-02-12)

Download OpenAPI specification:Download

API Support: help@uploadcare.com

An API that provides several ways of uploading files to Uploadcare‘s servers.

Upload

Direct uploads

Direct upload comply with the RFC 7578 standard and work by making POST requests via HTTPS.

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. See Storage Workflow for details.

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project secret key and hence should be crafted on your back end. See Signed uploads for details.

expire
number

expire sets the time until your signature is valid. It is timestamp. See Signed uploads for details.

Responses

200

Uploaded file UUID.

400

Request parameters validation errors.

403

This is most common errors you can get by the HTTP 403 response code.

413

Direct uploads only support files smaller than 100MB

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"
}

Direct form uploads

If you do not want to use Uploadcare Widget or one of our API clients for all kinds of uploads, this is a way to route your web forms through Uploadcare, so that we upload files submitted with your form and resend that form with no actual files but their UUIDs to a URL of your choice.

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. See Storage Workflow for details.

UPLOADCARE_ACTION
required
string <uri>

The URL to resubmit your form with file UUIDs to.

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project secret key and hence should be crafted on your back end. See Signed uploads for details.

expire
number

expire sets the time until your signature is valid. It is timestamp. See Signed uploads for details.

Responses

200

Files successfully uploaded.

400

Parameters errors

403

This is most common errors you can get by the HTTP 403 response code.

429

Request was throttled.

post/submit/

Production Server

https://upload.uploadcare.com/submit/

Request samples

Content type
multipart/form-data
Example
Copy
{
  "UPLOADCARE_PUB_KEY": "demopublickey",
  "UPLOADCARE_STORE": 1,
  "UPLOADCARE_ACTION": "https://my-app.com/my-form-handler/",
  "my_file.jpg": "@my_file.jpg"
}

Response samples

Content type
text/plain
Example
Copy
UPLOADCARE_ACTION should be a valid URL.

Start multipart upload

Multipart Uploads are useful when you are dealing with files larger than 100MB or explicitly want to use accelerated uploads.

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. See Storage Workflow for details.

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 hence should be crafted on your back end. See Signed uploads for details.

expire
number

expire sets the time until your signature is valid. It is timestamp. See Signed uploads for details.

Responses

200

Multipart upload start response.

400

Request parameters validation errors.

403

This is most 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 the provided 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 the byte order stays unchanged. Make sure to define 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 files 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

In a response, you get a JSON holding your uploaded file information.

400

Request parameters validation errors.

403

This is most 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. Your users will then be able to attach file links in your application.

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. See Storage Workflow for details.

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. 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 used if you believe a source_url will be used more than once. If you don’t explicitly define save_URL_duplicates, it is by default set to the value of check_URL_duplicates.

signature
string

signature is a string sent along with your upload request. It requires your Uploadcare project secret key and hence should be crafted on your back end. See Signed uploads for details.

expire
number

expire sets the time until your signature is valid. It is timestamp. See Signed uploads for details.

Responses

200

Response structure depends on the type field of response 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 upload.

Responses

200

If everything is ok and status is success, returns a JSON dictionary holding an uploaded file info. Here is a list of possible upload statuses are 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

Return 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":
    {