Managing files

Alongside upload functionality, Uploadcare provides additional methods for managing already uploaded files with its REST API. Organize your files further by tagging them, creating new file versions, making decisions based on file info, and running heavy tasks in the background.

Our REST API is documented in the OpenAPI 3 format. We'll provide links to the respective operations along this guide.


Basic building blocks of our API:

  • C — upload, create, copy
  • R — list files, get file info
  • U — store, add arbitrary and processing metadata
  • D — delete

Here is a basic example of a CRUD operation: retrieving the list of files.

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

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

const paginatedListOfFiles = paginate(listOfFiles)
const pages = paginatedListOfFiles(
  { authSchema: uploadcareSimpleAuthSchema }

for await (const page of pages) {
  for (const file of page.results) {
    console.log(`URL: ${file.url}`)

You can learn about uploading files in the respective article. Everything else is down below.

Get file info

List of filesGET /files/
File infoGET /files/{uuid}

You can list files in your project and get their info. File info provides you with insights into the content of the file. Based on the file information, you can decide to keep or delete it, create a modified copy, add metadata, or process it in other ways. Read down below about these features.

Keep or remove files

Store filePUT /files/{uuid}/storage/
Batch file storingPUT /files/storage/
Delete fileDELETE /files/{uuid}/storage/
Batch file deleteDELETE /files/storage/

If you haven't stored the file during uploading, you can store it afterwards to keep it from being removed after 24 hours. This might be the case if you look into file info before making a decision. This operation is possible for up to 100 files in one go.

You can also delete files anytime, also up to 100 in one go. Note, that the delete operation removes the file from storage but doesn't invalidate the CDN cache. You can change cache duration or submit a support ticket to invalidate selected files.

Files are immutable, but you can make their local copies to create new file versions.

As for changing the file name, you can apply any name when delivering it.

Catch file events with webhooks

List of webhooksGET /webhooks/
Create webhookPOST /webhooks/
Update webhookPUT /webhooks/{id}
Delete webhookDELETE /webhooks/unsubscribe

Uploadcare can notify your application about certain events with webhooks. For example, you may need to add or update a record in your database when a new file has been uploaded, or copy it to the remote storage if it qualifies your criteria. Read more about webhooks.

Copy locally and remotely

Copy file to local storagePOST /files/local_copy/
Copy file to remote storagePOST /files/remote_copy/

A local copy is used when you want to create a version of the current file. For example, when you need to "bake in" changes to the image you made. Or when you receive a big video file and want to encode it in an efficient format and smaller size.

Remote copy is helpful when you need to manually copy selected files to your S3 bucket to establish a specific file workflow.

Add arbitrary matadata

Get file's metadataGET /files/{uuid}/metadata/
Get metadata key's valueGET /files/{uuid}/metadata/{key}/
Update metadata key's valuePUT /files/{uuid}/metadata/{key}/
Delete metadata keyDELETE /files/{uuid}/metadata/{key}/

You can add additional, arbitrary key-value data associated with uploaded files. For example, you could store user IDs, order IDs, or tags. This is available both during and after. Read more about arbitrary file metadata.

Async processing

Type of operationPath
ConversionPOST conversion operation, GET job status
Add-onsPOST execute add-on, GET execution status

We have articles about each of these operations:

API integrations

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

REST API v0.7 (supports all API features):

REST API v0.6 (doesn't support all features, see lib documentation):

Uploadcare Dashboard

API methods mentioned above run our Dashboard, where you can view your files and perform such operations.

You can easily build your own dashboards. We have a few examples of how it can be done:

Analyze project usage

View your project project-analytics:

  • CDN traffic
  • Uploads
  • Popular files
  • Storage
  • Video processing
  • Document conversion
  • Object recognition
  • Background removal
  • API requests
  • API errors breakdown

Debug with API logs

Detailed API logs are helpful for debugging purposes.