Uploadcare REST API

Uploadcare features a simple, yet detailed API to manage projects and files. Note that REST API is the lowest level of access to Uploadcare and is implemented into every client. This means that if you aren't a library writer, you are perhaps better off using one of the clients for a language you prefer.

This section of our documentation is written in compliance with the RFC 2119 best practices of using key words to indicate requirement levels.

The REST API root is https://api.uploadcare.com/ via HTTPS. We try to keep it RESTful. You send data via query string and POST forms, you receive JSON responses. All URLs SHOULD end with a forward slash /.

Forming a request

In order to authenticate your account, every request made to https://api.uploadcare.com/ MUST be signed. Uploadcare allows its users to choose between the two auth-schemes:

  • Uploadcare.Simple, a simple authentication method with intuitive auth-param.
  • Uploadcare, a more complex yet more secure method.

Every request MUST contain the Authorization header, Authorization: auth-scheme auth-param, where the auth-param differs amidst the authentication methods.

Every request MAY contain the Accept header in order to specify the provided data type and the API version, Accept: application/vnd.uploadcare-v0.5+json If no version info is specified, a default API version is assumed (ver. 0.5 by now.)

Uploadcare.Simple auth-scheme

With Uploadcare.Simple authentication method, auth-param is a public_key:secret_key pair. Thus, the secret_key of your Uploadcare project is included in every request.

Please, look through the example request headers for Uploadcare.Simple,

Accept: application/vnd.uploadcare-v0.5+json
Authorization: Uploadcare.Simple public_key:private_key

Uploadcare auth-scheme

With Uploadcare authentication method:

  • auth-param is a public_key:signature pair, where your secret_key is used to derive signature, but is not included in every request itself.
  • Date header (formatted according to RFC 2822 MUST be provided in the request, and the date itself MUST NOT exceed the 15 minutes offset from the server time of the API endpoint.

Please, look through the example request headers for Uploadcare,

Accept: application/vnd.uploadcare-v0.5+json
Date: Fri, 30 Sep 2016 11:10:54 GMT
Authorization: Uploadcare ac58a21ea143ffa4f1af:6ff75027649aadd4dc98c1f784444445d1e6ed82

signature part of the Uploadcare authentication method auth-param MUST be constructed from the following components,

  • Request type (POST, GET, HEAD, OPTIONS).
  • Hex md5 hash of the request body.
  • Content-Type header value.
  • Data header value.
  • URI (including path and parameters). The above-listed parameters are then concatenated in textual order, using LF (every value sits in a separate line). The concatenation result is then signed using SHA1 algorithm, utilizing a secret_key of a project as a key.

Take a look at the Python example of the signature calculation (here, the request is made to obtain a list of files),

# importing the needed libraries
import hashlib
import hmac
from email import utils
from datetime import datetime
import time

# specifying the project's key (demo key is used for this example)
SECRET_KEY = 'demoprivatekey'

# specifying request type
verb = 'GET'

# calculating md5, since we sending an empty string —
# md5 calculations are performed for an empty string
content_md5 = hashlib.md5('').hexdigest()

# Content-Type header
content_type = 'application/json'

# Date header
date_header = utils.formatdate(usegmt=True)

# URI
uri = '/files/?limit=1&stored=true'

# forming the final string
sign_string = '\n'.join([verb, content_md5, content_type, date_header, uri])

# calculating the signature
signature = hmac.new(SECRET_KEY, sign_string, hashlib.sha1).hexdigest()

# Done

After the signature is calculated, it is implemented into the request body,

  $ curl  \
         -H "Content-Type: application/json" \
         -H "Accept: application/vnd.uploadcare-v0.5+json" \
         -H "Date: Fri, 30 Sep 2016 12:11:58 -0000" \
         -H "Authorization: Uploadcare demopublickey:170e3a56f5cb70adcb25e6cddb5d34aa8620aca9" \
         "https://api.uploadcare.com/files/?limit=1&stored=true"

Please, note that,

  • All date and time strings used with the API MUST be in the ISO 8601 extended format.
  • For pyuploadcare implementation of the Uploadcare authentication method, you may refer here.

Web Interface

We've added a web interface for the REST API at https://api.uploadcare.com/. This is done for you to practice interacting with the API by simply using a browser to follow the API URLs. By using the web interface you're able to send different kinds of requests and inspect the respective responses.

File Resource

The File Resource is intended to handle user-uploaded files and is the main Uploadcare resource.

Each of the uploaded files has a UUID that is assigned once and never changes then. So, it's safe to store file UUIDs in your database or even in your Moleskine.

Property Type Value
datetime_removed string or null Date and time when a file was removed, if any.
datetime_stored string or null Date and time of the last store request, if any.
datetime_uploaded string Date and time when a file was uploaded.
is_image boolean true, if a file is an image and can be modified via CDN, false otherwise.
is_ready boolean If a file is ready and not deleted, it is available on CDN.
mime_type string File MIME type.
original_file_url string or null Publicly available file CDN URL. Available only if a file is not deleted.
original_filename string Original name of an uploaded file.
size number File size in bytes.
url string API resource URL for a particular file.
uuid string File UUID.
image_info object Image meta (if a file is an image):
  • width and height
  • orientation
  • geo location (from EXIF)
  • original datetime (from EXIF)
  • format
  • resolution, DPI
  • Get a paginated list of files.

    GET /files/
    

    All query parameters are optional:

    removed

    true to include removed files only, false to include present files. Default is false.

    stored

    true to include stored files only, false to include temporary ones. Default is unset (both stored and not stored files are returned).

    limit

    Preferred amount of files in a list for a single response. Default is 100, maximum is 1000.

    ordering

    Specify the way files should be sorted in a returned list.

    Options:

    • datetime_uploaded — by upload time, ascending order.
    • -datetime_uploaded — by upload time, descending order.
    • size - by file size, ascending order.
    • -size - by file size, descending order.

    Default ordering option is datetime_uploaded.

    from

    A starting point for filtering files. The value depends on the set ordering parameter.

    If ordering=datetime_uploaded then a datetime MUST be used, YYYY-MM-DDTHH:MM:SS, where T is used as a separator. Example:

    ?ordering=-datetime_uploaded&from=2015-09-10T10:00:00
    

    If ordering=size then an integer file size MUST be used. File sizes SHOULD be set in bytes. Example:

    ?ordering=size&from=12909
    

    Example request:

    $ curl -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           "https://api.uploadcare.com/files/?stored=true&limit=10&from=5000&ordering=-size"
    

    Example response:

    {
      "next": "https://api.uploadcare.com/files/?from=3100&ordering=-size&stored=true&limit=10&offset=0",
      "previous": null,
      "total": 1893,
      "per_page": 10,
      "results": [
        {
          "original_file_url": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png",
          "image_info": {
            "height": 45,
            "width": 91,
            "geo_location": null,
            "datetime_original": null,
            "format": "PNG"
          },
          "mime_type": "image/png",
          "is_ready": true,
          "url": "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/",
          "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
          "original_filename": "image.png",
          "datetime_uploaded": "2014-08-24T11:18:08.216Z",
          "size": 4726,
          "is_image": true,
          "datetime_stored": "2014-08-24T11:18:20.430Z",
          "datetime_removed": null,
          "source": null
        },
        ...
      ]
    }
    
  • Copy uploaded file to a specified storage.

    POST /files/
    

    POST requests are used to copy original or modified (e.g. resized) file versions to custom storages or the default one. Source files MAY be either stored or just uploaded and MUST NOT be deleted.

    POST parameters:

    source

    Either a CDN URL or a UUID of a file subjected to copy. For example, http://www.ucarecdn.com/85b5644f-e692-4855-9db0-8c5a83096e25/-/resize/200x/roof.jpg.

    If provided source value is invalid, method returns an error:

    {"detail": "Bad `source` parameter. Use UUID or CDN URL."}
    

    If the source parameter is missing, method returns an error:

    {"detail": "`source` parameter is required."}
    
    target

    (Optional) Name of a custom storage connected to your project. Uploadcare storage is used if target is absent.

    If provided target does not exist, then method returns an error:

    {"detail": "Project has no storage with provided name."}
    
    store

    (Optional) Applicable to Uploadcare storage only. MUST be either true or false.

    true to store files while copying. If stored, files won't be automatically deleted within 24 hours after copying. false to not store files, default.

    In case provided value is invalid, method returns an error:

    {"detail": "`store` parameter should be `true` or `false`."}
    
    make_public

    (Optional) Applicable to custom storage only. MUST be either true or false. true to make copied files available via public links. false to reverse the behavior.

    In case provided value is invalid, method returns an error:

    {"detail": "`make_public` parameter should be `true` or `false`."}
    
    pattern

    (Optional) Applies to custom storage usage scenario only. The parameter is used to specify file names Uploadcare passes to custom storages. In case parameter is omitted, custom storage pattern is used.

    Allowed values:

    ${default} = ${uuid}/${auto_filename}
    ${auto_filename} = ${filename} ${effects} ${ext}
    ${effects} = CDN operations put into a URL
    ${filename} = original filename, no extension
    ${uuid} = file UUID
    ${ext} = file extension, leading dot, e.g. .jpg

    In case of an invalid value, method returns an error:

    {"detail": "Invalid pattern provided: `pattern_value`"}
    

    In case of an invalid symbol found in a pattern,

    {"detail": "Invalid pattern provided: Invalid character in a pattern."}
    

    POST request returns a JSON dictionary containing type and result fields. For url type, result is a URL with s3 scheme. Bucket name is put as a host. An s3 object path follows. For example:
    s3://my-bucket/85b5644f-e692-4855-9db0-8c5a83096e25/roof.resize_200x.jpeg

    Copy operation is synchronous. This means new files can be used upon a request completion. Hence, copy request may take some time for large files.

    Example request:

    $ curl -X POST \
           -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -d "source=03ccf9ab-f266-43fb-973d-a6529c55c2ae" \
           -d "store=true" \
           "https://api.uploadcare.com/files/"
    

    Example response:

    {
      "type": "file",
      "result": {
        "original_file_url": "http://www.ucarecdn.com/d1d2dc43-4904-4783-bb4d-fbcf64264e63/image.png",
        "image_info": {
          "height": 45,
          "width": 91,
          "geo_location": null,
          "datetime_original": null,
          "format": "PNG"
        },
        "mime_type": "image/png",
        "is_ready": true,
        "url": "https://api.uploadcare.com/files/d1d2dc43-4904-4783-bb4d-fbcf64264e63/",
        "uuid": "d1d2dc43-4904-4783-bb4d-fbcf64264e63",
        "original_filename": "image.png",
        "datetime_uploaded": "2014-09-09T16:48:57.284Z",
        "size": 0,
        "is_image": null,
        "datetime_stored": "2014-09-09T16:48:57.291Z",
        "datetime_removed": null,
        "source": "/03ccf9ab-f266-43fb-973d-a6529c55c2ae/"
      }
    }
    

    Example request:

    $ curl -X POST \
           -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -d "source=03ccf9ab-f266-43fb-973d-a6529c55c2ae" \
           -d "target=mytarget" \
           "https://api.uploadcare.com/files/"
    

    Example response:

    {
        "type": "url",
        "result": "s3://mybucket/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png"
    }
    

    Example request:

    $ curl -X POST \
           -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -d "source=03ccf9ab-f266-43fb-973d-a6529c55c2ae/-/resize/20x/" \
           -d "target=mytarget" \
           "https://api.uploadcare.com/files/"
    

    Example response:

    {
      "type": "url",
      "result": "s3://mybucket/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.resize_20x.png"
    }
    

    Error messages

    All of the listed errors are returned with HTTP 400 Bad Request status code.

    When file is not yet uploaded,

    {"detail": "File is not ready yet."}
    

    If copied file is too large,

    {"detail": "Copying of large files is not supported at the moment."}
    

    If current plan does not cover requested feature,

    {"detail": "Not allowed on your current plan."}
    
  • Store many files at once:

    PUT /files/storage/
    

    Delete many files at once:

    DELETE /files/storage/
    

    Up to 100 files are supported per request. File list SHOULD be put into a request body in form of a JSON object.

    Example request:

    $ curl -X PUT \
           -H "Content-Type: application/json" \
           -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -d '["21975c81-7f57-4c7a-aef9-acfe28779f78",
                "cbaf2d73-5169-4b2b-a543-496cf2813dff"]' \
           "https://api.uploadcare.com/files/storage/"
    

    Example response:

    {
      "status":"ok",
      "result":[
        {
          "uuid":"21975c81-7f57-4c7a-aef9-acfe28779f78",
          "original_file_url":"http://www.ucarecdn.com/21975c81-7f57-4c7a-aef9-acfe28779f78/image28MB.jpg",
          "image_info":{
              "orientation":null,
              "format":"JPEG",
              "height":1200,
              "width":1920,
              "geo_location":null,
              "datetime_original":null
          },
          "mime_type":"image/jpeg",
          "is_ready":true,
          "url":"https://api.uploadcare.com/files/21975c81-7f57-4c7a-aef9-acfe28779f78/",
          "original_filename":"image2.8MB.jpg",
          "datetime_uploaded":"2015-1209T03:47:24.952489Z",
          "size":2863008,
          "is_image":true,
          "datetime_stored":"2015-12-09T03:47:24.971880Z",
          "datetime_removed":null,
          "source":null
        },
        {
          "uuid":"cbaf2d73-5169-4b2b-a543-496cf2813dff",
          ...
        }
      ]
    }
    

    In case file list provided in a request holds invalid UUID(s), the response will contain problems structure. By calling UUIDs invalid here, we mean that certain files from the list might not exist, UUIDs might be incomplete, etc.

    {
      "status": "ok",
      "problems": {
        "21975c81-7f57-4c7a-aef9-acfe28779f78": "Missing in the project",
        "4j334o01-8bs3": "Invalid"
      },
      "result":[
        {
          "uuid": "cbaf2d73-5169-4b2b-a543-496cf2813dff",
          ...
        }
      ]
    }
    

    Possible errors

    If sent data is not a list,

    {"detail": "Expected list of UUIDs"}
    

    If a sent list is empty,

    {"detail": "List of UUIDs can not be empty"}
    

    If count of UUIDs exceeds the allowed limit per request,

    {"detail": "Maximum UUIDs per request is exceeded. The limit is 100"}
    
  • Get a file object with a specified UUID.

    GET /files/:uuid/
    

    Example request:

    $ curl -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/"
    

    Example response:

    {
      "original_file_url": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png",
      "image_info": {
        "height": 45,
        "width": 91,
        "geo_location": null,
        "datetime_original": null,
        "format": "PNG"
      },
      "mime_type": "image/png",
      "is_ready": true,
      "url": "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/",
      "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
      "original_filename": "image.png",
      "datetime_uploaded": "2014-08-24T11:18:08.216Z",
      "size": 4726,
      "is_image": true,
      "datetime_stored": "2014-08-24T11:18:20.430Z",
      "datetime_removed": null,
      "source": null
    }
    
  • Remove a file with a specified UUID.

    DELETE /files/:uuid/storage/
    

    or

    DELETE /files/:uuid/
    

    Example request:

    $ curl -I -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -X DELETE \
           "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/storage/"
    

    Example response:

    HTTP/1.1 302 FOUND
    Access-Control-Allow-Headers: Authorization
    Access-Control-Allow-Origin: https://uploadcare.com
    Allow: GET, POST, PUT, DELETE, OPTIONS, PATCH
    Content-Type: text/html; charset=utf-8
    Date: Sun, 31 Aug 2014 21:00:51 GMT
    Location: https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/
    Content-Length: 0
    
    ...
    

    Example request:

    $ curl -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -X DELETE \
           "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/"
    

    Example response:

    {
      "original_file_url": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png",
      "image_info": {
        "height": 45,
        "width": 91,
        "geo_location": null,
        "datetime_original": null,
        "format": "PNG"
      },
      "mime_type": "image/png",
      "is_ready": true,
      "url": "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/",
      "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
      "original_filename": "image.png",
      "datetime_uploaded": "2014-08-24T11:18:08.216Z",
      "size": 4726,
      "is_image": true,
      "datetime_stored": null,
      "datetime_removed": "2014-08-24T11:19:20.430Z",
      "source": null
    }
    
  • Put a file to the Uploadcare storage. The file will be available until removed via the API.

    PUT /files/:uuid/storage/
    

    Example request:

    $ curl -H "Authorization: Uploadcare.Simple demopublickey:demoprivatekey" \
           -X PUT \
           "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/storage/"
    

    Example response:

    {
      "original_file_url": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png",
      "image_info": {
        "height": 45,
        "width": 91,
        "geo_location": null,
        "datetime_original": null,
        "format": "PNG"
      },
      "mime_type": "image/png",
      "is_ready": true,
      "url": "https://api.uploadcare.com/files/03ccf9ab-f266-43fb-973d-a6529c55c2ae/",
      "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
      "original_filename": "image.png",
      "datetime_uploaded": "2014-08-24T11:18:08.216Z",
      "size": 4726,
      "is_image": true,
      "datetime_stored": "2014-08-24T11:21:20.430Z",
      "datetime_removed": null,
      "source": null
    }
    

Group Resource

Files can be joined into groups.

A group is an ordered list of files. Groups can hold files and respective CDN operations.

A group itself and files that make it MUST belong to the same project.

Usually, groups are created when users select many files for a single upload.

Important, groups are immutable. Hence, the only way to add/remove a file is to create a new group.

Groups are identified in a way similar to separate files, a group ID consists of: a UUID followed by a “~” tilde character and a group size (number of files in group). For example, this group holds 12 files, badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12.

Property Type Value
datetime_created string Date and time when a group was created.
datetime_stored string Date and time when files in a group were stored.
files_count number Count of files in a group.
cdn_url string Public CDN URL for a group.
files array List of files in a group. Deleted files are represented as null to preserve a number of files in a group in line with a group ID. This property is not available in group lists.
url string API resource URL for a group.
id string Group identifier.
  • Get a paginated list of groups.

    GET /groups/
    

    All query parameters are optional and MAY be omitted:

    limit

    Preferred number of groups per response. Default is 100, maximum is 1000.

    from

    A starting point for filtering group lists. MUST be a datetime value. Example:

    ?from=2015-01-02T10:00:00
    
    ordering

    Specify the sorting order of groups in a list.

    Options:

    • datetime_created - by creation time, ascending order.
    • -datetime_created - by creation time, descending order.

    datetime_created option is the default.

  • Get a group of files object, with a specified identifier.

    GET /groups/:group_id/
    
  • Mark all files in a group as stored after the 24-hour time (available on CDN).

    PUT /groups/:group_id/storage/
    

Project Resource

This provides basic information about the project you connect to.

Property Type Value
collaborators array List of collaborators.
name string Project login name.
pub_key string Project public key.

Each project object has a list of collaborators.

Property Type Value
email string Collaborator email.
name string Collaborator name.
  • Get information about a project.

    GET /project/
    

Pagination

Every resource that returns a collection (e.g. files) is paginated. That is, items in the collection are returned in batches. Every returned batch object has the following structure.

Property Type Value
next string URL of the next page.
previous string URL of the previous page.
total number Total count of queried objects.
per_page string Number of objects per page.
results array List of paginated objects. See documentation for specific objects structure.

Webhooks

You can use webhooks to receive notifications about your uploads. For instance, after a file has been uploaded into your project, we can send a notification to a provided URL.

We provide the two main concepts to use with webhooks:

  • subscription — contains the target_url that we need to touch when an event occurs.
  • notification — actual payload that will be sent to active subscriptions.
  • Get active subscriptions

    GET /webhooks/
    

    Example request:

    $ curl -H "Authorization: Uploadcare.Simple publickey:privatekey" \
           "https://api.uploadcare.com/webhooks/"
    

    Example response:

    [
      {
          "id": 1,
          "created": "2016-04-27T11:49:54.948615Z",
          "updated": "2016-04-27T12:04:57.819933Z",
          "event": "file.uploaded",
          "target_url": "http://sometargeturl.com/hooks/receiver",
          "project": 13,
          "is_active": true
      }
    ]
    
  • Create a new subscription

    POST /webhooks/
    

    Required parameters:

    target_url

    A URL that will be triggered by an event, e.g. file upload. Such URL MUST be unique for each project — event type combination.

    event

    An event to subscribe to. Currently, we only support the file.uploaded event.

    Optional parameters:

    is_active

    Marks a subscription as either active or not, defaults to true (active).

    Takes values: 1, true, True to mark a subscription as active. 0, false or False can be used otherwise.

    Example request:

    $ curl -X POST \
       -H "Authorization: Uploadcare.Simple publickey:privatekey" \
       -d "target_url=http://sometargeturl.com/hooks/receiver/second" \
       -d "event=file.uploaded" \
       "https://api.uploadcare.com/webhooks/"
    
  • Update subscription parameters

    POST /webhooks/:subscription_id/
    

    Fields available for updating:

    • target_url
    • event
    • is_active

    You can provide one or all fields with a single request. If any of the fields is not provided, its value won't be affected.

    Example request:

    $ curl -X POST \
       -H "Authorization: Uploadcare.Simple publickey:privatekey" \
       -d "is_active=true" \
       "https://api.uploadcare.com/webhooks/35/"
    
  • Delete subscription

    POST /webhooks/unsubscribe/
    

    Required parameters are identical to the ones for the subscribe method.

    Example request:

    $ curl -X POST \
       -H "Authorization: Uploadcare.Simple publickey:privatekey" \
       -d "target_url=http://sometargeturl.com/hooks/receiver/second" \
       -d "event=file.uploaded" \
       "https://api.uploadcare.com/webhooks/unsubscribe/"
    

    On success, the unsubscribe method returns a 204 status code without a message.

  • An example of a notification that will be sent when the file.uploaded event occurs:

    {
      "hook": {
          "id": 2,
          "event": "file.uploaded",
          "target": "http://sometargeturl.com/hooks/receiver/second"
      },
      "data": {
          "uuid": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
          "is_image": true,
          "filename": "image.png",
          "is_stored": true,
          "done": 64819,
          "file_id": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
          "original_filename": "image.png",
          "image_info": {
            "height": 45,
            "width": 91,
            "geo_location": null,
            "datetime_original": null,
            "format": "PNG"
          },
          "is_ready": true,
          "total": 4726,
          "size": 4726
      },
      "file": "http://www.ucarecdn.com/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png"
    }
    

Errors

Uploadcare uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success while codes in the 4xx range indicate errors caused by providing Uploadcare with invalid parameters, etc. Codes within the 5xx range indicate errors with Uploadcare servers (these are rare).

HTTP Code Description
200 — OK Everything worked as expected.
400 — Bad Request A request wasn't accepted, often due to missing parameters.
401 — Unauthorized No valid API key provided.
403 — Forbidden Access to resource is denied.
404 — Not Found The requested resource doesn't exist.
405 — Method not allowed Request method not supported, e.g. when using POST instead of GET.
429 — Too Many Requests Too many requests hit the API too quickly.
500, 502, 503, 504 — Server Errors Something went wrong on our side (these are rare.)

Each of the API error responses provides a JSON object (except for the 502, 503, and 504 server errors) which holds detail key with detailed information about an error.

  • Example request:

    $ curl https://api.uploadcare.com/files/
    

    Example response:

    {"detail": "Authentication credentials were not provided."}
    

For more information about errors which may occur when addressing particular resources, please read their respective sections.

If you haven't found what you were looking for in these docs, try looking in our Knowledge Base.