REST API Reference (0.5)

Download OpenAPI specification:Download

API Support: help@uploadcare.com

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.6+json

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

Every request MUST (MAY if you're using simple authentication scheme) 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: removed=true

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

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

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

limit
number [ 1 .. 1000 ]
Default: 1000
Example: limit=100

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

ordering
string
Default: "datetime_uploaded"
Enum: "datetime_uploaded" "-datetime_uploaded" "size" "-size"
Example: ordering=-datetime_uploaded

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

from
string

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

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

Version header.

Responses

200

A list of files, paginated.

401

Authorization errors.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

get /files/

Production Server

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

Response samples

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

Copy file

POST requests are used to copy original files or their modified versions to 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

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

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

Response samples

Content type
application/json
Copy
Expand all Collapse all
null

Store file

Store a single file by UUID.

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.

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

put /files/{uuid}/storage/

Production Server

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

Response samples

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

Delete file

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

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

File UUID.

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

Version header.

Responses

302

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

401

Authorization errors.

404

File not found.

406

Invalid version header Accept for this endpoint.

429

Request was throttled.

delete /files/{uuid}/storage/

Production Server

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

Response samples

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

Delete file (alternative)

Remove individual files. Returns file info.

Authorizations:
path Parameters
uuid
required
string <uuid>
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.

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

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

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.

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

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

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

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

Response samples

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