REST API Reference (0.6)

Download OpenAPI specification:Download

API support: help@uploadcare.com

REST API provides low-level access to Uploadcare features. You can access files, groups, projects, webhooks, document conversion and video encoding.

The REST API root is https://api.uploadcare.com/. Send data via query strings and POST request bodies, and receive JSON responses. All URLs MUST end with a forward slash /.

Check out the official and third party API clients that cover most of the popular programming languages and frameworks.

Authentication

apiKeyAuth

Every request made to https://api.uploadcare.com/ MUST be signed. HTTPS SHOULD be used with any authorization scheme.

Requests MUST contain the Authorization header defining auth-scheme and auth-param: Authorization: auth-scheme auth-param.

Every request SHOULD contain the Accept header identifying the REST API version: Accept: application/vnd.uploadcare-v0.6+json. If the Accept header is not present, a default API version is used: v0.5.

There are two available authorization schemes:

  • Uploadcare.Simple, a simple scheme where your Secret API Key MUST be specified in every request's auth-param.
  • Uploadcare, a more sophisticated scheme where a signature, not your Secret API Key MUST be specified. Signatures are then generated on your backend.
Security Scheme Type API Key
Header parameter name: Authorization

Uploadcare.Simple

With the Uploadcare.Simple authentication method, auth-param is your public_key:secret_key pair. With this scheme, your Uploadcare project secret_key gets included in every request.

Accept: application/vnd.uploadcare-v0.6+json
Authorization: Uploadcare.Simple public_key:secret_key
Security Scheme Type API Key
Header parameter name: Uploadcare.Simple

Uploadcare

With the 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.
  • You MUST also provide the Date header in RFC2822 format with the time zone set to GMT (see the example below).
  • The date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint.
Accept: application/vnd.uploadcare-v0.6+json
Date: Fri, 30 Sep 2016 11:10:54 GMT
Authorization: Uploadcare ac58a21ea143ffa4f1af:6ff75027649aadd4dc98c1f784444445d1e6ed82

The 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
  • Date header value
  • URI including path and parameters

The parameters are then concatenated in textual order using LF: every value sits in a separate line. The result is then signed with HMAC/SHA1 using your project's secret_key.

Take a look at the Python example of deriving signature; the example request is made to get a list of files:

import time
import hashlib
import hmac
from email import utils

# Specifying the project’s key (demo account Public API Key is used in this example)
SECRET_KEY = 'demosecretkey'

# Specifying request type
verb = 'GET'

# Calculate [md5](https://en.wikipedia.org/wiki/MD5) checksum for the request's HTTP body.
# Note: Taking into account that in our example, we are sending an HTTP GET request,
# and the request does not have anything in its HTTP body, we use an empty string as an input to the md5 hash function.
# If we were to send an HTTP POST request with, for example, JSON in the request's body,
# we would have to pass the JSON as the input to the md5 hash function.
content_md5 = hashlib.md5(b'').hexdigest()

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

# Current time, e.g. 1541423681
timestamp = int(time.time())
# Date header ('Mon, 05 Nov 2018 13:14:41 GMT')
date_header = utils.formatdate(timestamp, usegmt=True)

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

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

# Calculating the signature,
# the result may look like this: "3cbc4d2cf91f80c1ba162b926f8a975e8bec7995"
signature = hmac.new(SECRET_KEY.encode(), sign_string.encode(), hashlib.sha1).hexdigest()

Once signature is derived, it SHOULD be implemented into the request body:

curl  \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/vnd.uploadcare-v0.6+json' \
    -H 'Date: Mon, 05 Nov 2018 13:14:41 GMT' \
    -H 'Authorization: Uploadcare demopublickey:3cbc4d2cf91f80c1ba162b926f8a975e8bec7995' \
    'https://api.uploadcare.com/files/?limit=1&stored=true'
Security Scheme Type API Key
Header parameter name: Uploadcare

File

List of files

Getting a paginated list of files. If you need multiple results pages, use previous/next from the response to navigate back/forth.

Authorizations:
query Parameters
removed
boolean
Default: false
Example: removed=true

true to only include removed files in the response, false to include existing files. Defaults to false.

stored
boolean
Example: stored=true

true to only include files that were stored, false to include temporary ones. The default is unset: both stored and not stored files are returned.

limit
number [ 1 .. 1000 ]
Default: 100
Example: limit=100

A preferred amount of files in a list for a single response. Defaults to 100, while the maximum is 1000.

ordering
string
Default: "datetime_uploaded"
Enum: "datetime_uploaded" "-datetime_uploaded" "size" "-size"
Example: ordering=-datetime_uploaded

Specifies the way files are sorted in a returned list. field_name - ascending order, -field_name - descending order.

from
string

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

add_fields
string
Example: add_fields=rekognition_info

Add special fields to the file object, such as: rekognition_info.

header Parameters
Accept
required
string Nullable
Value: "application/vnd.uploadcare-v0.6+json"
Example: application/vnd.uploadcare-v0.6+json

Responses

Response samples

Content type
application/json
{}

Store file

Store a single file by UUID. When file is stored, it is available permanently. If not stored — it will only be available for 24 hours. If the parameter is omitted, it checks the Auto file storing setting of your Uploadcare project identified by the public_key provided in the auth-param.

Authorizations:
path Parameters
uuid
required
string <uuid>
Example: 21975c81-7f57-4c7a-aef9-acfe28779f78

File UUID.

header Parameters
Accept
required
string Nullable
Value: "application/vnd.uploadcare-v0.6+json"
Example: application/vnd.uploadcare-v0.6+json

Responses

Response samples

Content type
application/json
{
  • "rekognition_info": {
    },
  • "datetime_removed": null,
  • "datetime_stored": "2018-11-26T12:49:10.477888Z",
  • "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
  • "image_info": {