Download OpenAPI specification:Download
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.
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 |
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 |
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.Date
header in RFC2822 format with the time zone set to GMT
(see the example below).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:
POST
, GET
, HEAD
, OPTIONS
)Content-Type
header valueDate
header valueThe 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 |
Getting a paginated list of files. If you need multiple results pages, use previous
/next
from the response to navigate back/forth.
removed | boolean Default: false Example: removed=true
|
stored | boolean Example: stored=true
|
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. |
from | string A starting point for filtering files. The value depends on your |
add_fields | string Example: add_fields=rekognition_info Add special fields to the file object, such as: rekognition_info. |
Accept required | string Nullable Value: "application/vnd.uploadcare-v0.6+json" Example: application/vnd.uploadcare-v0.6+json |
{- "total": 2484,
- "totals": {
- "removed": 0,
- "stored": 2480,
- "unstored": 4
}, - "per_page": 2,
- "results": [
- {
- "rekognition_info": {
- "Art": 0.60401,
- "Home Decor": 0.719,
- "Ornament": 0.60401,
- "Shutter": 0.719,
- "Arabesque Pattern": 0.60401,
- "Window": 0.719,
- "Curtain": 0.719,
- "Brick": 0.75331,
- "Window Shade": 0.719,
- "Balcony": 0.70572
}, - "datetime_removed": null,
- "datetime_stored": "2018-11-26T12:49:10.477888Z",
- "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
- "image_info": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "sequence": false,
- "height": 500,
- "width": 500,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed",
- "variations": null,
- "video_info": null
}, - {
- "datetime_removed": null,
- "datetime_stored": "2021-09-21T11:24:33.159663Z",
- "datetime_uploaded": "2021-09-21T11:24:33.159663Z",
- "image_info": null,
- "is_image": false,
- "is_ready": true,
- "mime_type": "video/mp4",
- "original_file_url": "https://ucarecdn.com/7ed2aed0-0482-4c13-921b-0557b193edc2/16317390663260.mp4",
- "original_filename": "16317390663260.mp4",
- "size": 14479722,
- "uuid": "7ed2aed0-0482-4c13-921b-0557b193edc2",
- "variations": null,
- "video_info": {
- "audio": {
- "codec": "aac",
- "bitrate": 129,
- "channels": "2",
- "sample_rate": 44100
}, - "video": {
- "codec": "h264",
- "width": 640,
- "height": 480,
- "bitrate": 433,
- "frame_rate": 30
}, - "format": "mp4",
- "bitrate": 579,
- "duration": 200044
}
}
]
}
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
.
uuid required | string <uuid> Example: 21975c81-7f57-4c7a-aef9-acfe28779f78 File UUID. |
Accept required | string Nullable Value: "application/vnd.uploadcare-v0.6+json" Example: application/vnd.uploadcare-v0.6+json |
{- "rekognition_info": {
- "Art": 0.60401,
- "Home Decor": 0.719,
- "Ornament": 0.60401,
- "Shutter": 0.719,
- "Arabesque Pattern": 0.60401,
- "Window": 0.719,
- "Curtain": 0.719,
- "Brick": 0.75331,
- "Window Shade": 0.719,
- "Balcony": 0.70572
}, - "datetime_removed": null,
- "datetime_stored": "2018-11-26T12:49:10.477888Z",
- "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
- "image_info": {
- "color_mode": "RGB",
- "orientation": 6,
- "format": "JPEG",
- "sequence": false,
- "height": 500,
- "width": 500,
- "geo_location": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50"