Uploadcare REST API Reference
API docs by Redocly

REST API Reference (0.7)

Download OpenAPI specification:Download

API support: help@uploadcare.com

REST API provides low-level access to Uploadcare features. You can access files and their metadata, application data, file groups, add-ons, 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.7+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.7+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.7+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.7+json
Authorization: Uploadcare.Simple public_key:secret_key
Security Scheme Type: API Key
Header parameter name: Uploadcare.Simple

Integrations

You don't have to code most of the low-level API interactions. We have high-level libraries for all popular platforms:

In this API reference, you will see request examples in different languages. Keep in mind that running sample queries requires our libraries to be installed and initialized.

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
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"
Example: ordering=-datetime_uploaded

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

from
string
Example: from=2015-09-10T10:00:00Z

A starting point for filtering the files. If provided, the value MUST adhere to the ISO 8601 Extended Date/Time Format (YYYY-MM-DDTHH:MM:SSZ).

include
string
Example: include=appdata

Include additional fields to the file object, such as: appdata.

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

Version header.

Responses

Request samples 

import {
  listOfFiles,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await listOfFiles(
  {},
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
Example
{}

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

Version header.

Responses

Request samples 

import {
  storeFile,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await storeFile(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "datetime_removed": null,
  • "datetime_stored": "2018-11-26T12:49:10.477888Z",
  • "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
  • "variations": null,
  • "is_image": true,
  • "is_ready": true,
  • "mime_type": "image/jpeg",
  • "original_file_url": "https://ucarecdn.com/22240276-2f06-41f8-9411-755c8ce926ed/pineapple.jpg",
  • "original_filename": "pineapple.jpg",
  • "size": 642,
  • "url": "https://api.uploadcare.com/files/22240276-2f06-41f8-9411-755c8ce926ed/",
  • "uuid": "22240276-2f06-41f8-9411-755c8ce926ed",
  • "content_info": {
    },
  • "metadata": {
    },
  • "appdata": {
    }
}

Delete file

Removes individual files. Returns file info.

Note: this operation removes the file from storage but doesn't invalidate CDN cache.

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

File UUID.

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

Version header.

Responses

Request samples 

import {
  deleteFile,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await deleteFile(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "datetime_removed": "2018-11-26T12:49:11.477888Z",
  • "datetime_stored": null,
  • "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
  • "variations": null,
  • "is_image": true,
  • "is_ready": true,
  • "mime_type": "image/jpeg",
  • "original_file_url": "https://ucarecdn.com/22240276-2f06-41f8-9411-755c8ce926ed/pineapple.jpg",
  • "original_filename": "pineapple.jpg",
  • "size": 642,
  • "url": "https://api.uploadcare.com/files/22240276-2f06-41f8-9411-755c8ce926ed/",
  • "uuid": "22240276-2f06-41f8-9411-755c8ce926ed",
  • "content_info": {
    },
  • "metadata": {
    },
  • "appdata": {
    }
}

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.

query Parameters
include
string
Example: include=appdata

Include additional fields to the file object, such as: appdata.

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

Version header.

Responses

Request samples 

import {
  fileInfo,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await fileInfo(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
Example
{
  • "datetime_removed": null,
  • "datetime_stored": "2018-11-26T12:49:10.477888Z",
  • "datetime_uploaded": "2018-11-26T12:49:09.945335Z",
  • "variations": null,
  • "is_image": true,
  • "is_ready": true,
  • "mime_type": "image/jpeg",
  • "original_file_url": "https://ucarecdn.com/22240276-2f06-41f8-9411-755c8ce926ed/pineapple.jpg",
  • "original_filename": "pineapple.jpg",
  • "size": 642,
  • "url": "https://api.uploadcare.com/files/22240276-2f06-41f8-9411-755c8ce926ed/",
  • "uuid": "22240276-2f06-41f8-9411-755c8ce926ed",
  • "content_info": {
    },
  • "metadata": {
    },
  • "appdata": {
    }
}

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 or null
Example: application/vnd.uploadcare-v0.7+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.

Note: this operation removes files from storage but doesn't invalidate CDN cache.

Authorizations:
apiKeyAuth
header Parameters
Accept
required
string or null
Example: application/vnd.uploadcare-v0.7+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": [
    ]
}

Copy file to local storage

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

Version header.

Request Body schema: application/json
required
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.

metadata
object

Arbitrary additional metadata.

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "type": "file",
  • "result": {
    }
}

Copy file to remote storage

POST requests are used to copy original files or their modified versions to a custom 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. File size MUST NOT exceed 5 GB.

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

Version header.

Request Body schema: application/json
required
source
required
string <uri>

A CDN URL or just UUID of a file subjected to copy.

target
required
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
boolean
Default: true

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",
  • "target": "mytarget"
}

Response samples

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

File metadata

File metadata is additional, arbitrary data, associated with uploaded file. As an example, you could store unique file identifier from your system.

Metadata is key-value data. You can specify up to 50 keys, with key names up to 64 characters long and values up to 512 characters long. Read more in the docs.

Notice: Do not store any sensitive information (bank account numbers, card details, etc.) as metadata.

Notice: File metadata is provided by the end-users uploading the files and can contain symbols unsafe in, for example, HTML context. Please escape the metadata before use according to the rules of the target runtime context (HTML browser, SQL query parameter, etc).

Get file's metadata

Get file's metadata keys and values.

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

File UUID.

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

Version header.

Responses

Request samples 

import {
  getMetadata,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await getMetadata(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "subsystem": "uploader",
  • "pet": "cat"
}

Get metadata key's value

Get the value of a single metadata key.

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

File UUID.

key
required
string [ 1 .. 64 ] characters [\w\-\.\:]+
Example: subsystem

Key of file metadata. List of allowed characters for the key:

  • Latin letters in lower or upper case (a-z,A-Z)
  • digits (0-9)
  • underscore _
  • a hyphen -
  • dot .
  • colon :
header Parameters
Accept
required
string or null
Example: application/vnd.uploadcare-v0.7+json

Version header.

Responses

Request samples 

import {
  getMetadataValue,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await getMetadataValue(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
    key: 'pet'
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
"uploader"

Update metadata key's value

Update the value of a single metadata key. If the key does not exist, it will be created.

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

File UUID.

key
required
string [ 1 .. 64 ] characters [\w\-\.\:]+
Example: subsystem

Key of file metadata. List of allowed characters for the key:

  • Latin letters in lower or upper case (a-z,A-Z)
  • digits (0-9)
  • underscore _
  • a hyphen -
  • dot .
  • colon :
header Parameters
Accept
required
string or null
Example: application/vnd.uploadcare-v0.7+json

Version header.

Request Body schema: application/json
required
string [ 1 .. 512 ] characters

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
"uploader"

Delete metadata key

Delete a file's metadata key.

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

File UUID.

key
required
string [ 1 .. 64 ] characters [\w\-\.\:]+
Example: subsystem

Key of file metadata. List of allowed characters for the key:

  • Latin letters in lower or upper case (a-z,A-Z)
  • digits (0-9)
  • underscore _
  • a hyphen -
  • dot .
  • colon :
header Parameters
Accept
required
string or null
Example: application/vnd.uploadcare-v0.7+json

Version header.

Responses

Request samples 

import {
  deleteMetadata,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await deleteMetadata(
  {
    uuid: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
    key: 'delete_key',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "detail": "Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead."
}

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

Version header.

Responses

Request samples 

import {
  listOfGroups,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await listOfGroups({}, { authSchema: uploadcareSimpleAuthSchema })

Response samples

Content type
application/json
{}

Group info

Get a file group by its ID.

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

Version header.

Responses

Request samples 

import {
  groupInfo,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await groupInfo(
  {
    uuid: 'c5bec8c7-d4b6-4921-9e55-6edb027546bc~1',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{}

Delete group

Delete a file group by its ID.

Note: The operation only removes the group object itself. All the files that were part of the group are left as is.

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

Group UUID.

header Parameters
Accept
required
string or null
Value: "application/vnd.uploadcare-v0.7+json"
Example: application/vnd.uploadcare-v0.7+json

Version header.

Responses

Request samples 

import {
  deleteGroup,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await deleteGroup(
  {
    uuid: 'c5bec8c7-d4b6-4921-9e55-6edb027546bc~1',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "detail": "Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead."
}

Add-Ons

An Add-On is an application implemented by Uploadcare that accepts uploaded files as an input and can produce other files and/or appdata as an output.

Execute AWS Rekognition

Execute AWS Rekognition Add-On for a given target to detect labels in an image. Note: Detected labels are stored in the file's appdata.

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

Version header.

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

Unique ID of the file to process

Responses

Request samples

Content type
application/json
{
  • "target": "21975c81-7f57-4c7a-aef9-acfe28779f78"
}

Response samples

Content type
application/json
{
  • "request_id": "8db3c8b4-2dea-4146-bcdb-63387e2b33c1"
}

Check AWS Rekognition execution status

Check the status of an Add-On execution request that had been started using the Execute Add-On operation.

Authorizations:
apiKeyAuth
query Parameters
request_id
required
string <uuid>

Request ID returned by the Add-On execution request described above.

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

Version header.

Responses

Request samples 

<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->addons();
$status = $api->checkAwsRecognition('request-id');
echo \sprintf('Recognition status: %s', $status);

Response samples

Content type
application/json
{
  • "status": "in_progress"
}

Execute AWS Rekognition Moderation

Execute AWS Rekognition Moderation Add-On for a given target to detect moderation labels in an image. Note: Detected moderation labels are stored in the file's appdata.

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

Version header.

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

Unique ID of the file to process

Responses

Request samples

Content type
application/json
{
  • "target": "21975c81-7f57-4c7a-aef9-acfe28779f78"
}

Response samples

Content type
application/json
{
  • "request_id": "8db3c8b4-2dea-4146-bcdb-63387e2b33c1"
}

Check AWS Rekognition Moderation execution status

Check the status of an Add-On execution request that had been started using the Execute Add-On operation.

Authorizations:
apiKeyAuth
query Parameters
request_id
required
string <uuid>

Request ID returned by the Add-On execution request described above.

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

Version header.

Responses

Request samples 

<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->addons();
$status = $api->checkAwsRecognitionModeration('request-id');
echo \sprintf('Recognition status: %s', $status);

Response samples

Content type
application/json
{
  • "status": "in_progress"
}

Execute ClamAV

Execute ClamAV virus checking Add-On for a given target.

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

Version header.

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

Unique ID of the file to process

object
Default: {}

Optional object with Add-On specific parameters

Responses

Request samples

Content type
application/json
{
  • "target": "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "request_id": "8db3c8b4-2dea-4146-bcdb-63387e2b33c1"
}

Check ClamAV execution status

Check the status of an Add-On execution request that had been started using the Execute Add-On operation.

Authorizations:
apiKeyAuth
query Parameters
request_id
required
string <uuid>

Request ID returned by the Add-On execution request described above.

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

Version header.

Responses

Request samples 

import {
  addonExecutionStatus,
  AddonName,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await addonExecutionStatus(
  {
    addonName: AddonName.UC_CLAMAV_VIRUS_SCAN,
    requestId: '1bac376c-aa7e-4356-861b-dd2657b5bfd2',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "status": "in_progress"
}

Execute Remove.bg

Execute remove.bg background image removal Add-On for a given target.

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

Version header.

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

Unique ID of the file to process

object
Default: {}

Optional object with Add-On specific parameters

Responses

Request samples

Content type
application/json
{
  • "target": "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "params": {
    }
}

Response samples

Content type
application/json
{
  • "request_id": "8db3c8b4-2dea-4146-bcdb-63387e2b33c1"
}

Check Remove.bg execution status

Check the status of an Add-On execution request that had been started using the Execute Add-On operation.

Authorizations:
apiKeyAuth
query Parameters
request_id
required
string <uuid>

Request ID returned by the Add-On execution request described above.

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

Version header.

Responses

Request samples 

<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->addons();
$status = $api->checkRemoveBackground('request-id');
echo \sprintf('Remove background status: %s', $status);

Response samples

Content type
application/json
{
  • "result": {
    },
  • "status": "done"
}

Project

Project info

Getting info about account project.

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

Version header.

Responses

Request samples 

<?php
$configuration = Uploadcare\Configuration::create((string) $_ENV['UPLOADCARE_PUBLIC_KEY'], (string) $_ENV['UPLOADCARE_SECRET_KEY']);

$api = (new Uploadcare\Api($configuration))->project();
$projectInfo = $api->getProjectInfo();
echo \sprintf("Project %s info:\n", $projectInfo->getName());
echo \sprintf("Public key: %s\n", $projectInfo->getPubKey());
echo \sprintf("Auto-store enabled: %s\n", $projectInfo->isAutostoreEnabled() ? 'yes' : 'no');
foreach ($projectInfo->getCollaborators() as $email => $name) {
    echo \sprintf("%s: %s\n", $name, $email);
}

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

Version header.

Responses

Request samples 

import {
  listOfWebhooks,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await listOfWebhooks({}, { authSchema: uploadcareSimpleAuthSchema })

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

Version header.

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

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

event
required
string (webhook_event)
Enum: "file.uploaded" "file.infected" "file.stored" "file.deleted" "file.info_updated"

An event you subscribe to.

is_active
boolean (webhook_is_active)
Default: true

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

signing_secret
string <password> (webhook_signing_secret) <= 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 (webhook_version_of_request)
Default: "0.7"
Value: "0.7"

Webhook payload's version.

Responses

Callbacks

Request samples 

import {
  createWebhook,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await createWebhook(
  {
    targetUrl: 'https://yourwebhook.com',
    event: 'file.uploaded',
    isActive: true,
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

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.infected",
  • "target_url": "http://example.com/hooks/receiver",
  • "is_active": true,
  • "signing_secret": "7kMVZivndx0ErgvhRKAr",
  • "version": "0.7"
}

Callback payload samples

Callback
Content type
application/json
{
  • "initiator": {
    },
  • "hook": {
    },
  • "data": {
    },
  • "file": "http://example.com"
}

Update webhook

Update webhook attributes.

Authorizations:
apiKeyAuth
path Parameters
id
required
number
Example: 143

Webhook ID.

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

Version header.

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

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

event
string (webhook_event)
Enum: "file.uploaded" "file.infected" "file.stored" "file.deleted" "file.info_updated"

An event you subscribe to.

is_active
boolean (webhook_is_active)
Default: true

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

signing_secret
string <password> (webhook_signing_secret) <= 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

Request samples 

import {
  updateWebhook,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await updateWebhook(
  {
    id: 1473151,
    targetUrl: 'https://yourwebhook.com',
    event: 'file.uploaded',
    isActive: true,
    signingSecret: 'webhook-secret',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

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.infected",
  • "target_url": "http://example.com/hooks/receiver",
  • "is_active": true,
  • "signing_secret": "7kMVZivndx0ErgvhRKAr",
  • "version": "0.7"
}

Delete webhook

Unsubscribe and delete a webhook.

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

Version header.

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

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

Responses

Request samples 

import {
  deleteWebhook,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await deleteWebhook(
  {
    targetUrl: 'https://yourwebhook.com',
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
Example
{
  • "detail": "Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead."
}

Conversion

Document info

The endpoint allows you to determine the document format and possible conversion formats.

Authorizations:
apiKeyAuth
path Parameters
uuid
required
string
Example: 86c91c35-58e1-41f7-9b23-2d7652cfcd17

File uuid.

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

Version header.

Responses

Response samples

Content type
application/json
{
  • "error": null,
  • "format": {
    },
  • "converted_groups": {
    }
}

Convert document

Uploadcare allows you to convert files to different target formats. Check out the conversion capabilities for each supported format.

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

Version header.

Request Body schema: application/json
required
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.

save_in_group
string
Default: "0"
Enum: "0" "false" "1" "true"

When save_in_group is set to "1", multi-page documents additionally will be saved as a file group.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

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

Version header.

Responses

Request samples 

import {
  conversionJobStatus,
  ConversionType,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await conversionJobStatus(
  {
    type: ConversionType.DOCUMENT,
    token: 32921143
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "status": "processing",
  • "error": null,
  • "result": {
    }
}

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

Version header.

Request Body schema: application/json
required
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
{
  • "problems": {
    },
  • "result": [
    ]
}

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

Version header.

Responses

Request samples 

import {
  conversionJobStatus,
  ConversionType,
  UploadcareSimpleAuthSchema,
} from '@uploadcare/rest-client';

const uploadcareSimpleAuthSchema = new UploadcareSimpleAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
});

const result = await conversionJobStatus(
  {
    type: ConversionType.VIDEO,
    token: 1201016744
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

Response samples

Content type
application/json
{
  • "status": "processing",
  • "error": null,
  • "result": {
    }
}

Changelog

Document conversion info, November 7, 2023

GET /convert/document/{uuid}/ allows you to determine the document format and possible conversion formats.

Learn more about Document conversion.

Multipage conversion, September 20, 2023

Added save_in_group parameter to allow POST /convert/document/ to convert a multi-page document into a group of files.

Learn more about Multipage conversion.

Webhook updates, July 7, 2023

Added a field initiator in webhook payload for all events. It contains a "link" to the entity that initiated the webhook and metadata related to the event.

Added new webhook events:

  • file.info_updated — file's metadata or appdata has been altered.
  • file.deleted — a file has been removed.
  • file.stored — a file has been stored.

Learn more about Webhook events.

File metadata, September 8, 2022

File metadata is introduced. File metadata Upload API provides an option to specify a file's metadata during the file uploading procedure. File metadata REST API provides the ability to update the file's metadata.

GET /files/{uuid}/metadata/ Get file's metadata keys and values
GET /files/{uuid}/metadata/{key}/ Get the value of a single metadata key
PUT /files/{uuid}/metadata/{key}/ Update the value of a single metadata key. If the key does not exist, it will be created
DELETE /files/{uuid}/metadata/{key}/ Delete a file's metadata key
GET /files/{uuid}/ Field `metadata` that includes arbitrary metadata associated with a file

Learn more about File metadata management.

Changes to previous API version (released on 15 Aug 2022)

GET /files/{uuid}/ File information doesn't return `image_info` and `video_info` fields anymore

Added mime-type, image (dimensions, format, etc), video information (duration, format, bitrate, etc), audio information, etc. to `content_info` field

Associated field `appdata` that includes dictionary of application names and data with these applications

Removed `rekognition_info` in favor of `appdata`

Renamed Parameter `add_fields` to `include`
DELETE /files/{uuid}/ Removed in favour of `/files/{uuid}/storage/`
GET /files/ Remove the option of sorting the file list by file size
PUT /group/{uuid}/storage/ Removed. To store or remove files from a group, query the list of files in it, split the list into chunks of 100 files per chunk and then perform batch file storing or batch file removal for all the chunks
DELETE /group/{uuid}/ Added a possibility to delete a Group. Note: when we delete a group, we remove information about the group object itself, the files from the group are left intact
POST /addons/uc_clamav_virus_scan/execute/ Introduced ClamAV Add-On: perform virus scan on a target file
GET /addons/uc_clamav_virus_scan/execute/status/ Check ClamAV Add-On execution status
POST /addons/aws_rekognition_detect_labels /execute/ Introduced AWS Rekognition Add-On: detect labels on a target image and save results in the file's application data
GET /addons/aws_rekognition_detect_labels /execute/status/ Check AWS Rekognition Add-On execution status
POST /addons/aws_rekognition_detect_ moderation_labels/execute/ Introduced AWS Rekognition moderation Add-On: detect labels on a target image and save results in the file's application data
GET /addons/aws_rekognition_detect_ moderation_labels/execute/status/ Check AWS Rekognition moderation Add-On execution status
POST /addons/remove_bg/execute/ Introduced RemoveBG Add-On
GET /addons/remove_bg/execute/status/ Check RemoveBG Add-On execution status and get `file_id` with an UUID of the file with removed background

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.