REST API Reference (0.5)

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

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.5+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 formatted like in the example below (timezone must be always GMT) and the date you provide MUST NOT exceed the 15-minute offset from the server time of the API endpoint. Date and time strings used with the API MUST be in the ISO 8601 extended format.
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:

  • 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'

# Calculating md5, since we send an empty string,
# md5 calculations are performed for an empty string
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

File

List of files

Getting a paginated list of files.

Authorizations:
query Parameters
removed
string
Default: "false"
Enum: "true" "false"
Example: removed=true

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

stored
string
Enum: "true" "false"
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: 1000
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.

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

Responses

200

A list of files, paginated.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get/files/

Production Server

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Copy file

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.

Authorizations:
header Parameters
accept
required
string Nullable
Value: "application/vnd.uploadcare-v0.5+json"
Example: application/vnd.uploadcare-v0.5+json
Request Body schema: application/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 true or false. The true value makes copied files available via public links, false does the opposite.

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:

  • ${default} = ${uuid}/${auto_filename}
  • ${auto_filename} = ${filename}${effects}${ext}
  • ${effects} = processing operations put into a CDN URL
  • ${filename} = original filename without extension
  • ${uuid} = file UUID
  • ${ext} = file extension, including period, e.g. .jpg

Responses

200

Destination file with that name already exists. Check pattern parameter. This code is used only for remote copy.

201

The POST requests returns a JSON dictionary containing the type and result fields. For the URL type, the result is a URL with an s3 scheme. Your bucket name is put as a host, and an s3 object path follows.

400

Possible errors for file copy endpoint.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

post/files/

Production Server

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

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "source": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
  • "store": "true"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
null

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.5+json"
Example: application/vnd.uploadcare-v0.5+json

Responses

200

File stored. File info in a JSON.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

put/files/{uuid}/storage/

Production Server

https://api.uploadcare.com/files/{uuid}/storage/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Delete file

Remove individual files. Redirects to /files/<uuid>/.

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.5+json"
Example: application/vnd.uploadcare-v0.5+json

Responses

302

File deleted. Response is a redirect to /files/<uuid>/.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

delete/files/{uuid}/storage/

Production Server

https://api.uploadcare.com/files/{uuid}/storage/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "detail": "Incorrect authentication credentials."
}

Delete file (alternative)

Remove individual files. Returns file info.

Authorizations:
path Parameters
uuid
required
string <uuid>
<