REST API (0.5)

Download OpenAPI specification:Download

Uploadcare features a simple yet powerful REST API to manage projects and files. REST API is the lowest level of access to Uploadcare and is implemented into every client.

Authentication

apiKeyAuth

Every request made to https://api.uploadcare.com/ MUST be signed. To authenticate, requests MUST contain the Authorization header defining auth-scheme and auth-param,

`Authorization: auth-scheme auth-param`

There are two available authorization schemes:

  • Uploadcare.Simple, a simple scheme where your Secret API Key MUST be specified in every request's auth-param. Learn more in our docs.
  • Uploadcare, a more sophisticated scheme where a signature, not your Secret API Key MUST be specified. Signatures are then generated on your backend. Learn more in our docs.

Every request SHOULD contain the Accept header identifying the REST API version,

`Accept: application/vnd.uploadcare-v0.5+json`

If the Accept header is not present, a default API version is used: v0.5.

Every request MUST contain the Date header and the date MUST NOT exceed the 15-minute offset from the server time of the API endpoint. Learn more in our docs

Security scheme type: API Key
header parameter name: Authorization

File

List of files

Getting a paginated list of files.

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

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

stored
string
Enum:"true" "false"
Example: "true"

true to only include files that were stored, false to include temporary ones. The default is unset: both stored and not stored files are returned.

limit
number [ 1 .. 1000 ]
Default: 1000
Example: 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: "-datetime_uploaded"

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

from
string

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

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

Version header.

Responses

200

A list of files, paginated.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /files/
Production Server
https://api.uploadcare.com/files/

Response samples

application/json
Copy
Expand all Collapse all
{}

Copy file

POST requests are used to copy original files or their modified versions to default storage. Source files MAY either be stored or just uploaded and MUST NOT be deleted.

Authorizations:
header Parameters
accept
required
any
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. Implies you are copying a file to a specified custom storage. Keep in mind 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. true to make copied files available via public links, false to reverse the behavior.

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. In case the parameter is omitted, we use pattern of your custom storage. Use any combination of allowed values.

Responses

200

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

201

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

400

Simple auth. on HTTP and endpoint parameters errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

post /files/
Production Server
https://api.uploadcare.com/files/

Request samples

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

Response samples

application/json
Copy
Expand all Collapse all
null

File info

Once you obtain a list of files, you might want to acquire some file-specific info.

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

File UUID.

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

Version header.

Responses

200

File info in JSON.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /files/{uuid}/
Production Server
https://api.uploadcare.com/files/{uuid}/

Response samples

application/json
Copy
Expand all Collapse all
{}

Delete file

Beside deleting in a multi-file mode, you can remove individual files.

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

File UUID.

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

Version header.

Responses

200

File info in JSON.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

delete /files/{uuid}/
Production Server
https://api.uploadcare.com/files/{uuid}/

Response samples

application/json
Copy
Expand all Collapse all
{}

Store file

Store a single file by UUID.

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

File UUID.

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

Version header.

Responses

200

File stored. File info in JSON.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

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

Response samples

application/json
Copy
Expand all Collapse all
{}

Delete file 2

Same as DELETE /files/{uuid}/

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

File UUID.

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

Version header.

Responses

302

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

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

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

Response samples

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

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

Version header.

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

List of files UUIDs to store.

Responses

200

OK. See problems and result fields in the response. In case file list provided in a request holds invalid UUIDs, they will be included in the problems structure. Invalid UUIDs can be incomplete, associated with files that no longer exist, etc.

400

Files UUIDs list validation errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

put /files/storage/
Production Server
https://api.uploadcare.com/files/storage/

Request samples

application/json
Copy
Expand all Collapse all
[
  • "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]

Response samples

application/json
Copy
Expand all Collapse all
{
  • "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:
header Parameters
accept
required
any
Example: "application/vnd.uploadcare-v0.5+json"

Version header.

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

List of files UUIDs to store.

Responses

200

OK. See problems and result fields in the response. In case file list provided in a request holds invalid UUIDs, they will be included in the problems structure. Invalid UUIDs can be incomplete, associated with files that no longer exist, etc.

400

Files UUIDs list validation errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

delete /files/storage/
Production Server
https://api.uploadcare.com/files/storage/

Request samples

application/json
Copy
Expand all Collapse all
[
  • "21975c81-7f57-4c7a-aef9-acfe28779f78",
  • "cbaf2d73-5169-4b2b-a543-496cf2813dff"
]

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "ok",
  • "problems":
    {
    },
  • "result":
    []
}

Group

List of groups

Get a paginated list of groups.

Authorizations:
query Parameters
limit
number
Example: 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: "2015-01-02T10:00:00"

A starting point for filtering group lists. MUST be a datetime value with T used as a separator.

ordering
any
Default: "datetime_created"
Enum:"datetime_created" "-datetime_created"
Example: "-datetime_created"

Specifies the way groups are sorted in a returned list by creation time. datetime_created for ascending order, -datetime_created for descending order.

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

Version header.

Responses

200

A list of groups, paginated.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /groups/
Production Server
https://api.uploadcare.com/groups/

Response samples

application/json
Copy
Expand all Collapse all
{}

Group info

Get a file group by UUID.

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

Group UUID.

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

Version header.

Responses

200

JSON of requested group info.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

Group with uuid not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /groups/{uuid}/
Production Server
https://api.uploadcare.com/groups/{uuid}/

Response samples

application/json
Copy
Expand all Collapse all
{}

Store group

Mark all files in a group as stored.

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

Group UUID.

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

Version header.

Responses

200

Group successfully stored.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

404

Group with uuid not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

put /groups/<uuid>/storage/
Production Server
https://api.uploadcare.com/groups/<uuid>/storage/

Response samples

application/json
Copy
Expand all Collapse all
null

Project

Project

Getting info about account project.

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

Version header.

Responses

200

Your project details.

400

Simple authentication over HTTP is forbidden. Please, use HTTPS or signed requests instead.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /project/
Production Server
https://api.uploadcare.com/project/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "collaborators": [ ],
  • "name": "demo",
  • "pub_key": "demopublickey",
  • "autostore_enabled": true
}

Webhook

List of webhooks

List of project webhooks.

Authorizations:
header Parameters
accept
required
any
Example: "application/vnd.uploadcare-v0.5+json"

Version header.

Responses

200

List of project webhooks.

400

Simple auth. on HTTP and endpoint permission errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /webhooks/
Production Server
https://api.uploadcare.com/webhooks/

Response samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

Delete webhook

Unsubscribe and delete webhook.

Authorizations:
header Parameters
accept
required
any
Example: "application/vnd.uploadcare-v0.5+json"

Version header.

Request Body schema: application/x-www-form-urlencoded
name
string <uri>

Responses

204

Webhook successfully deleted.

400

Simple auth. on HTTP and endpoint permission errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

post /webhooks/unsubscribe/
Production Server
https://api.uploadcare.com/webhooks/unsubscribe/

Response samples

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

Update webhook

Update webhook attributes.

Authorizations:
path Parameters
id
required
number
Example: 143

Webhook ID.

Responses

200

Webhook attributes successfully updated.

401

Authorization errors.

404

Webhook with ID {id} not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

post /webhooks/<id>/
Production Server
https://api.uploadcare.com/webhooks/<id>/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": 1,
  • "created": "2016-04-27T11:49:54.948615Z",
  • "updated": "2016-04-27T12:04:57.819933Z",
  • "event": "file.uploaded",
  • "project": 13,
  • "is_active": true
}

Conversion

Convert document

Uploadcare allows converting documents to the following target formats: DOC, DOCX, XLS, XLSX, ODT, ODS, RTF, TXT, PDF, JPG, PNG.

Authorizations:
header Parameters
accept
required
any
Example: "application/vnd.uploadcare-v0.5+json"

Version header.

Request Body schema: application/json
paths
Array of string

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

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

A flag indicating if we should store your outputs.

Responses

200

Success.

400

Simple auth. on HTTP and endpoint permission errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

post /convert/document/
Production Server
https://api.uploadcare.com/convert/document/

Request samples

application/json
Copy
Expand all Collapse all
{}

Response samples

application/json
Copy
Expand all Collapse all
{}

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:
path Parameters
token
required
integer
Example: 426339926

Job token.

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

Version header.

Responses

200

Success.

400

Simple auth. on HTTP and endpoint permission errors.

401

Authorization errors.

404

Job with specified ID is not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

503

Conversion service error.

get /convert/document/status/{token}/
Production Server
https://api.uploadcare.com/convert/document/status/{token}/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "status": "processing",
  • "error": null,
  • "result":
    {
    }
}

Convert video

Uploadcare Video Processing optimizes your video content delivery. It is not just about using CDN nodes that suit your user locations, bandwidths, etc. You can adjust video quality, format, and size.

Authorizations:
header Parameters
accept
required
any
Example: "application/vnd.uploadcare-v0.5+json"

Version header.

Request Body schema: application/json
paths
Array of string

An array of UUIDs of your video files to process together with a set of needed operations.

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

A flag indicating if we should store your outputs.

Responses

200

Success.

400

Simple auth. on HTTP and endpoint permission errors.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

post /convert/video/
Production Server
https://api.uploadcare.com/convert/video/

Request samples

application/json
Copy
Expand all Collapse all
{
  • "paths":
    [
    ],
  • "store": 1
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "problems":
    [
    ],
  • "result":
    [