Uploadcare REST API Client

@uploadcare/rest-client is a JavaScript and TypeScript SDK for the Uploadcare REST API. It covers file management (upload, delete, copy to local/remote storage, metadata, tags), groups, webhooks, media conversion (video and document), and add-ons (virus scanning, image recognition, background removal). Works in Node.js and browser. Supports Simple and signature-based authentication, async pagination with generators, automatic retry with exponential backoff for throttled requests, and job status polling for async operations.

API Reference

 

• Install
• Usage
  • Authentication
  • API
  • Settings
  • Pagination
  • Job status polling
• Security issues
• Feedback

Install

npm install @uploadcare/rest-client
Copy

Usage

Authentication

Every REST API request should be authenticated using your secret key.

According to the spec, there are two available authentication methods:

1. Uploadcare.Simple
2. Uploadcare

Uploadcare.Simple authentication method

With the Uploadcare.Simple authentication method, your secret key gets included in every request. This method isn't secure enough because secret key is exposed to the runtime and will be transmitted over the network.

⚠️We strongly recommend not to use this method in production, especially on the client-side.⚠️

Example:

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 })
Copy

Uploadcare authentication method

With the Uploadcare authentication method, your secret key is used to derive signature but isn't included in every request itself.

Builtin signature resolver

You can use the builtin signature resolver, which automatically generates signature in-place using crypto module at Node.js or Web Crypto API at browsers.

import { UploadcareAuthSchema } from '@uploadcare/rest-client';

new UploadcareAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  secretKey: 'YOUR_SECRET_KEY',
})
Copy

⚠️We strongly recommend not to use builtin signature resolver on the client-side.⚠️

Custom signature resolver

This option is useful on the client-side to avoid secret key leak. You need to implement some backend endpoint, which will generate signature. In this case, secret key will be stored on your server only and will not be disclosed.

import { UploadcareAuthSchema } from '@uploadcare/rest-client';

new UploadcareAuthSchema({
  publicKey: 'YOUR_PUBLIC_KEY',
  signatureResolver: async (signString) => {
    /**
     * You need to make HTTPS request to your backend endpoint,
     * which should sign the `signString` using secret key.
     */
    const response = await fetch(`/sign-request?signString=${encodeURIComponent(signString)}`);
    const signature = await response.text();
    return signature;
  }
})
Copy

And then somewhere on your backend:

import { createSignature } from '@uploadcare/rest-client';

app.get('/sign-request', async (req, res) => {
  const signature = await createSignature('YOUR_SECREY_KEY', req.query.signString);
  res.send(signature);
})

Copy

API

You can use low-level wrappers to call the API endpoints directly:

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 })
Copy

List of all available API methods is available at the rest-client API Reference.

File tags

Files can carry a list of searchable string tags (API version 0.7). Use getTags to read them, replaceTags to overwrite the whole set, and updateTags to add and/or remove tags in a single atomic request:

import {
  getTags,
  replaceTags,
  updateTags,
  UploadcareSimpleAuthSchema
} from '@uploadcare/rest-client';

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

// Read the current tags
const { tags } = await getTags({ uuid: 'FILE_UUID' }, { authSchema });

// Replace the entire tag set
await replaceTags({ uuid: 'FILE_UUID', tags: ['cat', 'animal'] }, { authSchema });

// Add and remove tags at once (delete is applied before add)
const result = await updateTags(
  { uuid: 'FILE_UUID', add: ['dog', 'outdoor'], delete: ['cat'] },
  { authSchema }
);
// result: { tags, added, deleted }
Copy

See docs for normalization rules and limits.

Settings

List of all available Settings is available at the rest-client API Reference.

Pagination

We have the only two paginatable API methods - listOfFiles and listOfGroups. You can use one of those methods below to paginate over.

Using async generator and paginate() helper

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) {
  console.log(page)
}
Copy

Using Paginator class

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

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

const paginator = new Paginator(listOfFiles, {}, { authSchema: uploadcareSimpleAuthSchema })

while(paginator.hasNextPage()) {
  const page = await paginator.next()
  console.log(page)
}

while(paginator.hasPrevPage()) {
  const page = await paginator.prev()
  console.log(page)
}

console.log(paginator.getCurrentPage())
Copy

Check out the rest-client API Reference for the Paginator.

Job status polling

There are two helpers to do job status polling using Conversion API or Addons API: conversionJobPoller and addonJobPoller.

Conversion API

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

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

const abortController = new AbortController()
// abortController.abort()

const jobs = await conversionJobPoller(
  {
    type: ConversionType.VIDEO,
    // type: ConversionType.DOCUMENT,
    onRun: response => console.log(response), // called when job is started
    onStatus: response => console.log(response), // called on every job status request
    paths: [':uuid/video/-/size/x720/', ':uuid/video/-/size/x360/'],
    store: false,
    pollOptions: {
      signal: abortController.signal
    }
  },
  { authSchema: uploadcareSimpleAuthSchema }
)

const results = Promise.allSettled(jobs)

console.log(results)
Copy

Addons API

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

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

const abortController = new AbortController()
// abortController.abort()

const result = await addonJobPoller(
  {
    addonName: AddonName.UC_CLAMAV_VIRUS_SCAN,
    // addonName: AddonName.AWS_REKOGNITION_DETECT_LABELS,
    // addonName: AddonName.REMOVE_BG,
    onRun: response => console.log(response), // called when job is started
    onStatus: response => console.log(response), // called on every job status request
    target: ':uuid',
    params: {
      purge_infected: false
    },
    pollOptions: {
      signal: abortController.signal
    }
  },
  testSettings
)

console.log(result)
Copy

Security issues

If you think you ran into something in Uploadcare libraries that might have security implications, please hit us up at bugbounty@uploadcare.com or Hackerone.

We'll contact you personally in a short time to fix an issue through co-op and prior to any public disclosure.

Feedback

Issues and PRs are welcome. You can provide your feedback or drop us a support request at hello@uploadcare.com.