Uploading API

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

  • For JSON consumers
  • For web forms
  • Upload one or more files.

    POST /base/
    

    Query parameters:

    UPLOADCARE_PUB_KEY

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

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:

    UPLOADCARE_PUB_KEY

    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/
    

    Query parameters:

    pub_key

    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 parameter 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.

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

    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:

    token

    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:

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

    error

    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.

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

    signature

    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)
    
    expire

    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/
    

    Query parameters:

    pub_key

    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.
    

    Returns a JSON dictionary with file info.

    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/
    

    Query parameters:

    pub_key

    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.

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

    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/
    

    Query parameters:

    pub_key

    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.
    

    Returns a JSON dictionary with group info.

    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 that REST 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.
    
If you haven't found what you were looking for in these docs, try looking in our Knowledge Base.