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 our 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.5+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.5+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.5+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.5+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.
removed | string Default: "false" Enum: "true" "false" Example: removed=true
|
stored | string Enum: "true" "false" 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 ordering parameter value. |
Accept required | string Nullable Value: "application/vnd.uploadcare-v0.5+json" Example: application/vnd.uploadcare-v0.5+json |
{- "total": 2484,
- "per_page": 2,
- "results": [
- {
- "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": null,
- "format": "JPEG",
- "sequence": false,
- "height": 500,
- "width": 500,
- "geo_location": null,
- "datetime_original": null,
- "dpi": [
- 144,
- 144
]
}, - "is_image": true,
- "is_ready": true,
- "mime_type": "application/octet-stream",
- "original_filename": "papaya.jpg",
- "size": 642,
- "uuid": "3c269810-c17b-4e2c-92b6-25622464d866"
}, - {
- "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": null,
- "format": "JPEG",
- "sequence": false,
- "height": 500,
- "width": 500,
- "geo_location": null,
- "datetime_original": null,
- "dpi": [
- 144,
- 144
]
}, - "is_image": true,
- "is_ready": true,
- "mime_type": "application/octet-stream",
- "original_filename": "papaya.jpg",
- "size": 642,
- "uuid": "3c269810-c17b-4e2c-92b6-25622464d866"
}
]
}
POST requests are used to copy original files or their modified versions to a default storage.
Source files MAY either be stored or just uploaded and MUST NOT be deleted.
Copying of large files is not supported at the moment. If the file CDN URL includes transformation operators, its size MUST NOT exceed 100 MB. If not, the size MUST NOT exceed 5 GB.
Accept required | string Nullable Value: "application/vnd.uploadcare-v0.5+json" Example: application/vnd.uploadcare-v0.5+json |
source required | string <uri> A CDN URL or just UUID of a file subjected to copy. |
store | string Default: "false" Enum: "true" "false" The parameter only applies to the Uploadcare storage and MUST be either true or false. |
target | string Identifies a custom storage name related to your project. It implies that you are copying a file to a specified custom storage. Keep in mind that you can have multiple storages associated with a single S3 bucket. |
make_public | string Default: "true" Enum: "true" "false" MUST be either |
pattern | string Default: "${default}" Enum: "${default}" "${auto_filename}" "${effects}" "${filename}" "${uuid}" "${ext}" The parameter is used to specify file names Uploadcare passes to a custom storage. If the parameter is omitted, your custom storages pattern is used. Use any combination of allowed values. Parameter values:
|