Uploading API documentation

This is a complement to the REST API. This API provides several ways to upload files to our servers. Every Uploadcare client provides some form of file upload, so if you’re not a library writer, you are probably best off using one of the clients for your language of choice.

Every uploaded file is temporary until it is stored. This means that it will be automatically deleted after 24 hours from the time of upload. During this time you should store file to our storage or grab it to your server. You can also store file upon uploading with UPLOADCARE_STORE flag (see below). After upload, all files appear on the CDN.

The uploading API root is https://upload.uploadcare.com/ via HTTPS. You send us form data, you receive JSON responses. All URLs should end with a forward slash /.

File uploading in request body

Upload one or more files for JSON consumers

POST /base/

Query parameters

PropertyTypeValue
UPLOADCARE_PUB_KEYstring

Public key of target project.

UPLOADCARE_STORE

0 or is not set — do not store file upon uploading;
1 — store the file upon uploading. Requires “automatic file storing” setting to be enabled;
auto — store acording to project settings.

(other)

Files as form data, field names can be anything.

Returns a JSON dictionary, where keys correspond to file field names, and values are UUIDs of files from these fields.

Example request:

curl -F "UPLOADCARE_PUB_KEY=demopublickey" \
     -F "UPLOADCARE_STORE=1" \
     -F "file=@image.jpeg" \
     "https://upload.uploadcare.com/base/"

Example response:

{
  "file": "17be4678-dab7-4bc7-8753-28914a22960a"
}

File uploading for web forms

We don’t recommend using this feature unless you really have to. Try our widget instead! It uploads files in the background and has a really nice, customizable UI.

It is possible to route your web forms through Uploadcare, so that we upload files submitted with your form and resend the form with uploaded file UUIDs to a URL of your choice. All you have to do is point your form’s action attribute to https://upload.uploadcare.com/submit/ and place the original value of action in a hidden field named UPLOADCARE_ACTION.

For example, the following is a basic setup to use this feature:

<form method="POST" enctype="multipart/form-data"
      action="https://upload.uploadcare.com/submit/">

  <input type="hidden" name="UPLOADCARE_PUB_KEY" value="demopublickey">
  <input type="hidden" name="UPLOADCARE_ACTION" value="https://my-app.com/my-form-handler/">
  <input type="file" name="my-file">
</form>

Upload one or more files and resubmit form data.

POST /submit/

Query parameters

PropertyTypeValue
UPLOADCARE_PUB_KEYstring

Public key of target project.

UPLOADCARE_ACTION

The URL to submit the form to, after files are uploaded. If the parameter is missing, method returns an error:

[HTTP 400] UPLOADCARE_ACTION is required.

If provided URL for action is invalid, method returns an error:

[HTTP 400] UPLOADCARE_ACTION should be a valid URL.
UPLOADCARE_STORE

0 or is not set — do not store file upon uploading;
1 — store the file upon uploading. Requires “automatic file storing” setting to be enabled;
auto — store acording to project settings.

(other)

Any other form fields, including files. Field name can be anything.

All file fields will be replaced with UUIDs of respective uploaded files.

File uploading from URL

Upload file from specified URL.

GET /from_url/

Returns a JSON dictionary with the token, which can be used to receive uploading status. Please note, this token is not the file UUID. File UUID will be returned by the status method (see below).

Query parameters

PropertyTypeValue
pub_keystring

Public key of a target project. If the parameter is missing, method returns an error:

[HTTP 400] pub_key is required.
source_url

URL of source file. URL should be public HTTP or HTTPS link. If the parameter is missing, method returns an error:

[HTTP 400] source_url is required.
store

0 or is not set — do not store file upon uploading;
1 — store the file upon uploading. Requires “automatic file storing” setting to be enabled;
auto — store acording to project settings.

filename

(Optional) Name of the uploaded file. If this parameter is not specified the filename will be obtained from response headers or source URL.

Example request:

curl "https://upload.uploadcare.com/from_url/\
?pub_key=demopublickey&store=1\
&source_url=http%3A%2F%2Fabs.twimg.com%2Fb%2Ffront_page%2Fv1%2FEU_4.jpg"

Example response:

{
  "token": "945ebb27-1fd6-46c6-a859-b9893712d650"
}

Errors

If incorrect source_url is provided (e.g. not URL):

[HTTP 400] Failed to parse URL.

If information about URL scheme (like http://) for source_url is missing:

[HTTP 400] No URL scheme supplied.

Currently, only uploading only from http:// or https:// resources, otherwise an error is returned:

[HTTP 400] Invalid URL scheme.

If source_url does not exist (e.g. resource is gone):

[HTTP 400] Host does not exist.

If provided source_url in our blacklist:

[HTTP 400] Source is blacklisted.

If source_url contains malformed host:

[HTTP 400] URL host is malformed.

If provided source_url refers to a private IP (e.g. 192.168.0.1):

[HTTP 400] Only public IPs are allowed.

Uploading status for files uploaded from URL

GET /from_url/status/

Query parameter

PropertyTypeValue
tokenstring

Token returned by the upload from URL method. If the parameter is missing, method returns an error:

[HTTP 400] token is required.

Returns a JSON dictionary with status and additinal info. Status can be one of the following:

PropertyTypeValue
progress

Additional fields total and done are also returned with size in bytes. total can be null in some cases (i.e. when origin server does not give us the info).

errorstring

When error is occurred. Additional field error contains short description.

success

Uploading is complete. All fields from info request are also present.

Example request:

curl "https://upload.uploadcare.com/from_url/status/\
?token=3ef5d533-68fb-4039-8cd2-41a4d045db0a"

Example response:

{
  "status": "error",
  "error": "FileTooBig: 1150844928 > 104857600"
}

Example request:

curl "https://upload.uploadcare.com/from_url/status/\
?token=945ebb27-1fd6-46c6-a859-b9893712d650"

Example response:

{
  "status": "success",
  "is_stored": true,
  "done": 145212,
  "file_id": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "total": 145212,
  "size": 145212,
  "uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "is_image": true,
  "filename": "EU_4.jpg",
  "is_ready": true,
  "original_filename": "EU_4.jpg",
  "mime_type": "image/jpeg",
  "image_info": {
    "orientation": null,
    "format": "JPEG",
    "height": 640,
    "width": 960,
    "geo_location": null,
    "datetime_original": null
  }
}

Signed uploads

You can turn on this option for your project on its page. After that, all uploads will require an extra token sent to Upload API, and you’ll have full control over who and when can upload files to the project.

Parameters

You need to add next parameters to any uploading request via POST or query parameters.

PropertyTypeValue
signaturestring

A signature, sent along with upload request. It should be created on your back end (to keep your secret key, well, secret).

The signature is a MD5 hex-encoded hash from a concatenation of secret_key and expire.

In Python the process of generating signature might look like this:

import time
import hashlib
 def generate_secure_signature(secret, expire):
  to_sign = str(secret) + str(int(expire))
  return hashlib.md5(to_sign).digest().encode('hex')
 # Expire in 30 min e.g. 1454903856
expire = int(time.time()) + 60 * 30
 # secret key of your project
secret = 'project_secret_key'
 # example result: '04b29480233f4def5c875875b6bdc3b1'
signature = generate_secure_signature(secret, expire)
PropertyTypeValue
expirenumber

Unix time until the signature is valid e.g. 1454902434.

Example request:

curl -F "UPLOADCARE_PUB_KEY=caa9d29da887ee88ffe6" \
     -F "signature=04b29480233f4def5c875875b6bdc3b1" \
     -F "expire=1454903856" \
     -F "file=@image.jpg" \
     "https://upload.uploadcare.com/base/"

Example response:

{
  "file": "c0d776d4-8c8e-47df-9e92-03b68b99c2ba"
}

Possible errors

If you enable signed uploads for your project then both signature and expire parameters are required for every upload request. Otherwise, you’ll receive one of the following errors:

[HTTP 400] `signature` is required.
[HTTP 400] `expire` is required.

If expire is not a valid Unix timestamp:

[HTTP 400] `expire` must be a UNIX timestamp.

If signature is expired i.e. expire < now:

[HTTP 403] Expired signature.

If signature is incorrect:

[HTTP 403] Invalid signature.

Get file info

Get file info.

GET /info/

Returns a JSON dictionary with file info.

Query parameters

PropertyTypeValue
pub_keystring

Public key of target project. If the parameter is missing, method returns an error:

[HTTP 400] pub_key is required.
file_id

UUID of file. If the parameter is missing, method returns an error:

[HTTP 400] file_id is required.

Example request:

curl "https://upload.uploadcare.com/info/?pub_key=demopublickey\
&file_id=575ed4e8-f4e8-4c14-a58b-1527b6d9ee46"

Example response:

{
  "is_stored": true,
  "done": 145212,
  "file_id": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "total": 145212,
  "size": 145212,
  "uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46",
  "is_image": true,
  "filename": "EU_4.jpg",
  "is_ready": true,
  "original_filename": "EU_4.jpg",
  "mime_type": "image/jpeg",
  "image_info": {
    "orientation": null,
    "format": "JPEG",
    "height": 640,
    "width": 960,
    "geo_location": null,
    "datetime_original": null
  }
}

Creating groups

You can create a file group from a set of files. You can group files by their UUIDs or CDN URLs. Operations in CDN URLs are not stripped and kept with the file, when joining it in a group.

Create a group.

POST /group/

Returns a JSON or JSONP response with information about the group.

Query parameters

PropertyTypeValue
pub_keystring

Public key of target project. If the parameter is missing, method returns an error:

[HTTP 400] pub_key is required.
files[n]

Multiple ordered parameters, where n is a unique positive number or zero. Each parameter can be a file UUID or a CDN URL (with or without operations). If the parameter is missing or empty, method returns an error:

[HTTP 400] no files[N] parameters found.

If any of provided files is invlid UUID or CDN URL, method returns an error:

[HTTP 400] this is not valid file url: http://invalid/url.

If some files are missing in the project, then method returns an error:

[HTTP 400] some files not found.
callback

Name of the JSONP callback function.

Example request:

curl -F "pub_key=demopublickey" \
     -F "files[0]=d6d34fa9-addd-472c-868d-2e5c105f9fcd" \
     -F "files[1]=b1026315-8116-4632-8364-607e64fca723/-/resize/x800/" \
     "https://upload.uploadcare.com/group/"

Example response:

{
  "id": "6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2",
  "datetime_created": "2014-07-18T13:29:20.272Z",
  "datetime_stored": null,
  "files_count": 2,
  "cdn_url": "http://www.ucarecdn.com/6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2/",
  "url": "https://api.uploadcare.com/groups/6e5e2226-d4a6-459b-824d-ff5f8090eaf9~2/",
  "files": [
    {
      "default_effects": "",
      "is_stored": true,
      "uuid": "d6d34fa9-addd-472c-868d-2e5c105f9fcd",
      "is_image": true,
      "is_ready": true,
      ...
    },
    {
      "default_effects": "resize/x800/",
      "is_stored": true,
      "uuid": "b1026315-8116-4632-8364-607e64fca723",
      "is_image": true,
      "is_ready": true,
      ...
    }
  ]
}

Get group info

Get group info.

GET /group/info/

Returns a JSON dictionary with group info.

Query parameters

PropertyTypeValue
pub_keystring

Public key of target project. If the parameter is missing, method returns an error:

[HTTP 400] pub_key is required.
group_id

Group ID (UUID~N, where N is number of files in a group). If the parameter is missing, method returns an error:

[HTTP 400] group_id is required.

If group with provided group_id does not exist, then method returns an error:

[HTTP 404] group_id is invalid.

Example request:

curl "https://upload.uploadcare.com/group/info/?pub_key=demopublickey\
&group_id=d52d7136-a2e5-4338-9f45-affbf83b857d~2"

Example response:

{
  "id": "d52d7136-a2e5-4338-9f45-affbf83b857d~2",
  "datetime_created": "2015-09-21T12:39:13.743754Z",
  "datetime_stored": null,
  "files_count": 2,
  "cdn_url": "http://www.ucarecdn.com/d52d7136-a2e5-4338-9f45-affbf83b857d~2/",
  "url": "https://api.uploadcare.com/groups/d52d7136-a2e5-4338-9f45-affbf83b857d~2/",
  "files": [
    {
      "default_effects": "",
      "is_stored": true,
      "done": 122448,
      "file_id": "6e013b2b-a88b-45ff-9dba-9cc60c6531cc",
      "total": 122448,
      "size": 122448,
      "uuid": "6e013b2b-a88b-45ff-9dba-9cc60c6531cc",
      "is_image": true,
      "filename": "ScreenShot20110927at30439.jpeg",
      "is_ready": true,
      "original_filename": "Screen Shot 2011-09-27 at 3.04.39.jpeg",
      "image_info": {
        "orientation": 1,
        "format": "JPEG",
        "height": 826,
        "width": 718,
        "geo_location": null,
        "datetime_original": null
      }
    },
    {
      "default_effects": "",
      "is_stored": true,
      "done": 192519,
      "file_id": "0c081c58-6788-4b90-bb0e-6f0af0802294",
      "total": 192519,
      "size": 192519,
      "uuid": "0c081c58-6788-4b90-bb0e-6f0af0802294",
      "is_image": true,
      "filename": "201311152128.jpeg",
      "is_ready": true,
      "original_filename": "Снимок экрана 2013-11-15 в 21.28.jpeg",
      "image_info": {
        "orientation": 1,
        "format": "JPEG",
        "height": 898,
        "width": 834,
        "geo_location": null,
        "datetime_original": null
      }
    }
  ]
}

Errors

The Uploading API supports same convention about HTTP statuses for errors and thatREST API. But instead of returning JSON object with information about error, by default it returns an error message as plain text. If needed, you can turn on a representation of errors as JSON objects - just send jsonerrors=1 flag.

The Uploading API has some common errors such as:

If UPLOADCARE_PUB_KEY parameter is missing in the request:

[HTTP 403] UPLOADCARE_PUB_KEY is required.

If specified UPLOADCARE_PUB_KEY is invalid (e.g. project does not exist):

[HTTP 403] UPLOADCARE_PUB_KEY is invalid.

When store option is on for a request, but this option is disabled for the a project:

[HTTP 403] Autostore is disabled.

If account which owns the project is blocked:

[HTTP 403] Account has been blocked.

If account which owns the project is blocked for non payment:

[HTTP 403] Account has been blocked for non payment.

If account exceeds limits (this can only happen on free plans):

[HTTP 403] Account has reached its limits.

If uploaded file is too large:

[HTTP 400] File is too large.

Questions?

We're always happy to help with code or other questions you might have! Search our site for more information or send us an email!