Download OpenAPI specification:Download
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 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 MUST contain the Accept
header identifying the REST API version: Accept: application/vnd.uploadcare-v0.6+json
.
There are two available authorization schemes:
Uploadcare
, a scheme where a signature
, not your Secret API Key MUST be specified. Signatures SHOULD be generated on backend.Uploadcare.Simple
, a simple scheme where your Secret API Key MUST be specified in every request's auth-param
.Authorization
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 public_key: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
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.6+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'
Uploadcare
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.6+json
Authorization: Uploadcare.Simple public_key:secret_key
Uploadcare.Simple
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 Examples:
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 Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "total": 2484,
- "totals": {
- "removed": 0,
- "stored": 2480,
- "unstored": 4
}, - "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}, - {
- "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 Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "value": {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}, - "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
Remove individual files. Returns file info.
uuid required | string <uuid> Example: 21975c81-7f57-4c7a-aef9-acfe28779f78 File UUID. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "datetime_removed": "2018-11-26T12:49:11.477888Z",
- "datetime_stored": null,
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
Remove individual files. Returns file info.
uuid required | string <uuid> Example: 03ccf9ab-f266-43fb-973d-a6529c55c2ae File UUID. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "datetime_removed": "2018-11-26T12:49:11.477888Z",
- "datetime_stored": null,
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
Get file information by its UUID (immutable).
uuid required | string <uuid> Example: 03ccf9ab-f266-43fb-973d-a6529c55c2ae File UUID. |
add_fields | string Example: add_fields=rekognition_info Add special fields to the file object, such as: rekognition_info. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
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.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
List of file UUIDs to store.
[- "21975c81-7f57-4c7a-aef9-acfe28779f78",
- "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]
{- "status": "ok",
- "problems": {
- "21975c81-7f57-4c7a-aef9-acfe28779f78": "Missing in the project",
- "4j334o01-8bs3": "Invalid"
}, - "result": [
- {
- "value": {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}, - "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
]
}
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.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
List of file UUIDs to delete.
[- "21975c81-7f57-4c7a-aef9-acfe28779f78",
- "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]
{- "status": "ok",
- "problems": {
- "21975c81-7f57-4c7a-aef9-acfe28779f78": "Missing in the project",
- "4j334o01-8bs3": "Invalid"
}, - "result": [
- {
- "value": {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}, - "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
]
}
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 Example: application/vnd.uploadcare-v0.6+json Version header. |
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. |
{- "source": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
- "store": "true"
}
{- "type": "file",
- "result": {
- "value": {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}, - "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
}
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.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
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:
|
{- "source": "03ccf9ab-f266-43fb-973d-a6529c55c2ae",
- "target": "mytarget"
}
{- "type": "url",
- "result": "s3://mybucket/03ccf9ab-f266-43fb-973d-a6529c55c2ae/image.png"
}
Get a paginated list of groups.
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.
|
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "previous": null,
- "total": 100,
- "per_page": 2,
- "results": [
- {
- "id": "dd43982b-5447-44b2-86f6-1c3b52afa0ff~1",
- "datetime_created": "2018-11-27T14:14:37.583654Z",
- "datetime_stored": null,
- "files_count": 1,
}, - {
- "id": "fd59dbcb-40a1-4f3a-8062-cc7d23f66885~1",
- "datetime_created": "2018-11-27T15:14:39.586674Z",
- "datetime_stored": "2018-11-27T15:17:38.132584Z",
- "files_count": 1,
}
]
}
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.
uuid required | string Example: badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12 Group UUID. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "id": "dd43982b-5447-44b2-86f6-1c3b52afa0ff~1",
- "datetime_created": "2018-11-27T14:14:37.583654Z",
- "datetime_stored": null,
- "files_count": 1,
- "files": [
- {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
]
}
Mark all files within a group as stored.
uuid required | string Example: badfc9f7-f88f-4921-9cc0-22e2c08aa2da~12 Group UUID. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
{- "id": "fd59dbcb-40a1-4f3a-8062-cc7d23f66885~1",
- "datetime_created": "2018-11-27T15:14:39.586674Z",
- "datetime_stored": "2018-11-27T15:17:38.132584Z",
- "files_count": 1,
- "files": [
- {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "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
}, - "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
]
}
Getting info about account project.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
<?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);
}
{- "collaborators": [ ],
- "name": "demo",
- "pub_key": "YOUR_PUBLIC_KEY",
- "autostore_enabled": true
}
List of project webhooks.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 })
[- {
- "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.6"
}
]
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.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
event required | string (webhook_event) An event you subscribe to. |
is_active | boolean (webhook_is_active) Default: true Marks a subscription as either active or not, defaults to |
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 Calculated signature will be sent to the |
version | string (webhook_version) Default: "0.6" Enum: "0.6" "0.7" Webhook payload's version. |
{- "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.6"
}
{- "hook": {
- "id": 1,
- "project_id": 13,
- "project_pub_key": "2d199fbf3896699a2639",
- "created_at": "2016-04-27T11:49:54.948615Z",
- "updated_at": "2016-04-27T12:04:57.819933Z",
- "event": "file.uploaded",
- "is_active": true,
- "version": "0.6"
}, - "data": {
- "value": {
- "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": {
- "latitude": 55.62013611111111,
- "longitude": 37.66299166666666
}, - "datetime_original": "2018-08-20T08:59:50",
- "dpi": [
- 144,
- 144
]
}, - "video_info": null,
- "variations": null,
- "is_image": true,
- "is_ready": true,
- "mime_type": "image/jpeg",
- "original_filename": "pineapple.jpg",
- "size": 642,
- "uuid": "22240276-2f06-41f8-9411-755c8ce926ed"
}
},
}
Update webhook attributes.
id required | number Example: 143 Webhook ID. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
event | string (webhook_event) An event you subscribe to. |
is_active | boolean (webhook_is_active) Default: true Marks a subscription as either active or not, defaults to |
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 Calculated signature will be sent to the |
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 } )
{- "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.6"
}
Unsubscribe and delete a webhook.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
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 } )
{- "detail": "Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead."
}
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.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
{- "paths": [
- "88a51210-bd69-4411-bc72-a9952d9512cd/document/-/format/pdf/",
- "8ddbbb48-0927-4df7-afac-c6031668b01b"
], - "store": 1
}
{- "problems": {
- "8ddbbb48-0927-4df7-afac-c6031668b01b": "Bad path \"8ddbbb48-0927-4df7-afac-c6031668b01b\". Use UUID or CDN URL"
}, - "result": [
- {
- "token": 445630631,
- "uuid": "d52d7136-a2e5-4338-9f45-affbf83b857d"
}, - {
- "original_source": "88a51210-bd69-4411-bc72-a9952d9512cd/document/-/format/pdf/",
- "token": 445630637,
- "uuid": "28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2"
}
]
}
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
.
token required | integer Example: 426339926 Job token. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 } )
{- "status": "processing",
- "error": null,
- "result": {
- "uuid": "500196bc-9da5-4aaf-8f3e-70a4ce86edae"
}
}
Uploadcare video processing adjusts video quality, format (mp4, webm, ogg), and size, cuts it, and generates thumbnails. Processed video is instantly available over CDN.
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 |
{- "paths": [
- "d52d7136-a2e5-4338-9f45-affbf83b857d/video/",
- "d52d7136-a2e5-4338-9f45-affbf83b857d/video/-/format/ogg/-/quality/best/",
- "28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2"
], - "store": "1"
}
{- "problems": {
- "13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d": "Bad path \"13cd56e2-f6d7-4c66-ab1b-ffd13cd6646d\". Use UUID or CDN URL"
}, - "result": [
- {
- "original_source": "d52d7136-a2e5-4338-9f45-affbf83b857d/video/-/format/ogg/-/quality/best/",
- "token": 445630631,
- "thumbnails_group_uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46~1",
- "uuid": "d52d7136-a2e5-4338-9f45-affbf83b857d"
}, - {
- "original_source": "500196bc-9da5-4aaf-8f3e-70a4ce86edae/video/",
- "token": 445630637,
- "thumbnails_group_uuid": "be3b4d5e-179d-460e-8a5d-69112ac86cbb~1",
- "uuid": "28843a09-dd3d-4b8a-ad4f-8aa5f8f60ff2"
}
]
}
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
.
token required | integer Example: 426339926 Job token. |
Accept required | string Example: application/vnd.uploadcare-v0.6+json Version header. |
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 } )
{- "status": "processing",
- "error": null,
- "result": {
- "thumbnails_group_uuid": "575ed4e8-f4e8-4c14-a58b-1527b6d9ee46~1",
- "uuid": "500196bc-9da5-4aaf-8f3e-70a4ce86edae"
}
}
v0.5 —> v0.6
Path | Change |
---|---|
/files/ | Added file fields: `variations`, `video_info` |
/files/ | Added query param: `add_fields` for `rekognition_info` |
/files/ | POST requests were deprecated |
/files/storage/ | Added file fields: `variations`, `video_info` |
/files/storage/ | Added query param: `add_fields` for `rekognition_info` |
/files/local_copy/ | Introduced |
/files/remote_copy/ | Introduced |
/files/(?P |
Added file fields `variations`, `video_info` |
/files/(?P |
Added query param `add_fields` for `rekognition_info` |
/webhooks/unsubscribe/ | DELETE is used for unsubscribe action |
/webhooks/(?P |
PUT is used to update data |
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.