REST API Reference (0.5)

Download OpenAPI specification:Download

API support: help@uploadcare.com

Check out the latest API version.

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 MUST contain the Accept header identifying the REST API version: Accept: application/vnd.uploadcare-v0.5+json.

There are two available authorization schemes:

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

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.5+json
Date: Fri, 30 Sep 2016 11:10:54 GMT
Authorization: Uploadcare public_key: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
SECRET_KEY = 'YOUR_SECRET_KEY'

# 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 YOUR_PUBLIC_KEY:SIGNATURE' \
    'https://api.uploadcare.com/files/?limit=1&stored=true'
Security Scheme Type: API Key
Header parameter name: Uploadcare

Uploadcare.Simple

Note: We DO NOT recommend using this authentication method in production.

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

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

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:
apiKeyAuth
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: 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
Examples:
  • from=2015-09-10T10:00:00 - If ordering=datetime_uploaded then a datetime MUST be used, YYYY-MM-DDTHH:MM:SS, where T is used as a separator.
  • from=12909 - If ordering=size then an integer file size MUST be used. File sizes SHOULD be set in bytes.:

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

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

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:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

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

Request samples

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

Response samples

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

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:
apiKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 21975c81-7f57-4c7a-aef9-acfe28779f78

File UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

Delete file

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

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

File UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{
  • "detail": "Incorrect authentication credentials."
}

Delete file (alternative)

Remove individual files. Returns file info.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 03ccf9ab-f266-43fb-973d-a6529c55c2ae

File UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

File info

Get file information by its UUID (immutable).

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string <uuid>
Example: 03ccf9ab-f266-43fb-973d-a6529c55c2ae

File UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

Batch file storing

Used to store multiple files in one go. Up to 100 files are supported per request. A JSON object holding your File list SHOULD be put into a request body.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/json
required
Array
string <uuid>

List of file UUIDs to store.

Responses

Request samples

Content type
application/json
[
  • "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]

Response samples

Content type
application/json
{
  • "status": "ok",
  • "problems": {
    },
  • "result": []
}

Batch file delete

Used to delete multiple files in one go. Up to 100 files are supported per request. A JSON object holding your File list SHOULD be put into a request body.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/json
required
Array
string <uuid>

List of file UUIDs to delete.

Responses

Request samples

Content type
application/json
[
  • "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]

Response samples

Content type
application/json
{
  • "status": "ok",
  • "problems": {
    },
  • "result": []
}

Group

List of groups

Get a paginated list of groups.

Authorizations:
apiKeyAuth
query Parameters
limit
number
Example: limit=150

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

from
string <date-time>
Example: from=2015-01-02T10:00:00.463352Z

A starting point for filtering the list of groups. If passed, MUST be a date and time value in ISO-8601 format.

ordering
string
Default: "datetime_created"
Enum: "datetime_created" "-datetime_created"
Example: ordering=-datetime_created

Specifies the way groups should be sorted in the returned list. datetime_created for the ascending order (default), -datetime_created for the descending one.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

Group info

Get a file group by UUID.

Groups are identified in a way similar to individual files. A group ID consists of a UUID followed by a “~” (tilde) character and a group size: integer number of the files in the group.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string
Example: badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12

Group UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

Store group

Mark all files within a group as stored.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string
Example: badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12

Group UUID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{}

Project

Project

Getting info about account project.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{
  • "collaborators": [ ],
  • "name": "demo",
  • "pub_key": "YOUR_PUBLIC_KEY",
  • "autostore_enabled": true
}

Webhook

List of webhooks

List of project webhooks.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create webhook

Create and subscribe to a webhook. You can use webhooks to receive notifications about your uploads. For instance, once a file gets uploaded to your project, we can notify you by sending a message to a target URL.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/x-www-form-urlencoded
required
target_url
required
string <uri> <= 255 characters

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each projectevent type combination.

event
required
string

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

is_active
boolean
Default: true

Marks a subscription as either active or not, defaults to true, otherwise false.

signing_secret
string <password> <= 32 characters

Optional HMAC/SHA-256 secret that, if set, will be used to calculate signatures for the webhook payloads sent to the target_url.

Calculated signature will be sent to the target_url as a value of the X-Uc-Signature HTTP header. The header will have the following format: X-Uc-Signature: v1=<HMAC-SHA256-HEX-DIGEST>. See Secure Webhooks for details.

version
string
Default: "0.5"
Enum: "0.5" "0.6" "0.7"

Webhook payload's version.

Responses

Callbacks

Response samples

Content type
application/json
{
  • "id": 1,
  • "project": 13,
  • "created": "2016-04-27T11:49:54.948615Z",
  • "updated": "2016-04-27T12:04:57.819933Z",
  • "event": "file.uploaded",
  • "is_active": true,
  • "signing_secret": "7kMVZivndx0ErgvhRKAr",
  • "version": "0.5"
}

Callback payload samples

Callback
POST: file.uploaded event
Content type
application/json
{
  • "hook": {
    },
  • "data": {},
}

Update webhook

Update webhook attributes.

Authorizations:
apiKeyAuth
path Parameters
id
required
number
Example: 143

Webhook ID.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/x-www-form-urlencoded
required
target_url
string <uri> <= 255 characters

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each projectevent type combination.

event
string

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

is_active
boolean
Default: true

Marks a subscription as either active or not, defaults to true, otherwise false.

signing_secret
string <password> <= 32 characters

Optional HMAC/SHA-256 secret that, if set, will be used to calculate signatures for the webhook payloads sent to the target_url.

Calculated signature will be sent to the target_url as a value of the X-Uc-Signature HTTP header. The header will have the following format: X-Uc-Signature: v1=<HMAC-SHA256-HEX-DIGEST>. See Secure Webhooks for details.

Responses

Response samples

Content type
application/json
{
  • "id": 1,
  • "project": 13,
  • "created": "2016-04-27T11:49:54.948615Z",
  • "updated": "2016-04-27T12:04:57.819933Z",
  • "event": "file.uploaded",
  • "is_active": true,
  • "signing_secret": "7kMVZivndx0ErgvhRKAr",
  • "version": "0.5"
}

Delete webhook

Unsubscribe and delete a webhook.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/x-www-form-urlencoded
required
target_url
required
string <uri> <= 255 characters

A URL that is triggered by an event, for example, a file upload. A target URL MUST be unique for each projectevent type combination.

Responses

Response samples

Content type
application/json
Example
{
  • "detail": "You can\"t use webhooks"
}

Conversion

Convert document

Uploadcare allows document conversion to the following target formats: DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, PNG. Input file formats: DOC, DOCX, XLS, XLSX, PPS, PPSX, PPT, PPTX, VSD, VSDX, SKW, WPD, WPS, XLR, PUB, MPP, KEY, MSG, NUMBERS, PAGES, ODT, ODS, ODP, TXT, RTF, PDF, DJVU, EML, CSV, XPS, PS, EPS.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/json
paths
Array of strings

An array of UUIDs of your source documents to convert together with the specified target format (see documentation).

store
string
Enum: "0" "false" "1" "true"

When store is set to "0", the converted files will only be available for 24 hours. "1" makes converted files available permanently. 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."

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "value": {}
}

Document conversion job status

Once you get a conversion job result, you can acquire a conversion job status via token. Just put it in your request URL as :token.

Authorizations:
apiKeyAuth
path Parameters
token
required
integer
Example: 426339926

Job token.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Convert video

Uploadcare video processing adjusts video quality, format (mp4, webm, ogg), and size, cuts it, and generates thumbnails. Processed video is instantly available over CDN.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Request Body schema: application/json
paths
Array of strings

An array of UUIDs of your video files to process together with a set of assigned operations (see documentation).

store
string
Enum: "0" "false" "1" "true"

When store is set to "0", the converted files will only be available for 24 hours. "1" makes converted files available permanently. 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.

Responses

Request samples

Content type
application/json
{
  • "paths": [
    ],
  • "store": 1
}

Response samples

Content type
application/json
{
  • "value": {
    }
}

Video conversion job status

Once you get a processing job result, you can acquire a processing job status via token. Just put it in your request URL as :token.

Authorizations:
apiKeyAuth
path Parameters
token
required
integer
Example: 426339926

Job token.

header Parameters
Accept
required
string
Example: application/vnd.uploadcare-v0.5+json

Version header.

Responses

Response samples

Content type
application/json
{
  • "value": {
    }
}

Changelog

v0.4 —> v0.5

Path Change
/files/ Available ordering fields are: `size`, `-size`, `datetime_uploaded`, `-datetime_uploaded`
/groups/ Added pagination ordering fields : 'datetime_created', '-datetime_created'
/convert/video/ Introduced
/convert/video/status/ Introduced
/convert/document/ Introduced. Allows document conversion to the various target formats
/convert/document/status/ Introduced
/webhooks/ Support of REST API added — JSON support, params serialization, etc. Allowed only POST and GET
/webhooks/unsubscribe/ Support of REST API added — JSON support, params serialization, etc. POST is used for unsubscribe action
/webhooks/(?P\d+)/ Support of REST API added — JSON support, params serialization, etc

Versioning

When we introduce backward-incompatible changes, we release new major versions. Once published, such versions are supported for 2 years.

Version Date Published Available Until
0.7 15 Aug 2022 TBD
0.6 RC 15 Aug 2024
0.5 1 Apr 2016 15 Aug 2024
0.4 13 Jun 2015 1 Sep 2019
0.3 11 Jun 2013 1 Sep 2019
0.2 7 Jun 2012 1 Sep 2019
0.1 31 May 2012 1 Feb 2019
Undefined 31 May 2012 1 Sep 2019

Note, you won’t be able to use any API version after its support term. Requests to deprecated API versions will return error messages.

Other APIs

You can find the complete reference documentation for the Upload API here and URL API here.