Managing files

JS API clients

JS API clients handle uploads and file operations by wrapping Uploadcare Upload API and REST API. You can use it from within your Node.js app and in a browser.

JS API clients GitHub →

Features

Uploading (Upload API):

  • Upload files from local storage and URLs (up to 5 TB)
  • Multipart uploading for large files
  • Track uploading progress
  • Bulk file uploading
  • Uploading network to speed uploading jobs (like CDN)
  • Secure uploads (signed uploads)

File management (REST API):

  • Get file info and perform various operations (store/delete/copy) with them
  • Manage metadata
  • Manage webhooks
  • Convert documents
  • Encode and transform videos
  • Secure authentication

Image processing (URL API):

  • Compression
  • Geometry
  • Colors
  • Definition
  • Image and text overlays
  • Rotations
  • Recognition
  • File info
  • Proxy (fetch)

Requirements

Node.js 16 or later.

Install

$npm install @uploadcare/upload-client
$npm install @uploadcare/rest-client
$npm install @uploadcare/signed-uploads

Usage examples

To access the Upload Client High-Level API, you need to create an instance of UploadClient providing the necessary settings. Specifying YOUR_PUBLIC_KEY is mandatory. It points to the specific Uploadcare project:

1import { UploadClient } from '@uploadcare/upload-client'
2
3const client = new UploadClient({ publicKey: 'YOUR_PUBLIC_KEY' })

Once the UploadClient instance is created, you can start using the wrapper to upload files from binary data:

1client
2  .uploadFile(fileData)
3  .then(file => console.log(file.uuid))

Note: The store option accepts true, false, or "auto". String values like "true" or "false" are not accepted.

Signed uploads

To upload files securely, use the @uploadcare/signed-uploads package:

1import { generateSecureSignature } from '@uploadcare/signed-uploads'
2
3// Option A: expiration as timestamp in milliseconds
4const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
5  expire: Date.now() + 60 * 30 * 1000 // 30 minutes from now
6})
7
8// Option B: expiration as a Date object
9const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
10  expire: new Date("2099-01-01")
11})
12
13const client = new UploadClient({
14  publicKey: 'YOUR_PUBLIC_KEY',
15  secureSignature,
16  secureExpire,
17})

Bulk uploads

Use Queue to control concurrency when uploading multiple files:

1import { Queue, uploadFile } from '@uploadcare/upload-client'
2
3const queue = new Queue(10) // max 10 concurrent uploads
4
5await queue.add(() => uploadFile(file1, { publicKey: 'YOUR_PUBLIC_KEY' }))
6await queue.add(() => uploadFile(file2, { publicKey: 'YOUR_PUBLIC_KEY' }))

Error handling

1import { UploadError, NetworkError } from '@uploadcare/upload-client'
2
3try {
4  const file = await client.uploadFile(fileData)
5} catch (error) {
6  if (error instanceof NetworkError) {
7    console.error('Network error:', error.message)
8  } else if (error instanceof UploadError) {
9    console.error('Upload error:', error.message)
10  }
11}

Authentication

For server-side usage, use UploadcareSimpleAuthSchema:

1import { UploadcareSimpleAuthSchema } from '@uploadcare/rest-client'
2
3const authSchema = new UploadcareSimpleAuthSchema({
4  publicKey: 'YOUR_PUBLIC_KEY',
5  secretKey: 'YOUR_SECRET_KEY',
6})

Note: Never use UploadcareSimpleAuthSchema on the client side — it exposes your secret key. For client-side usage, use UploadcareAuthSchema with a signatureResolver that delegates signing to your backend. For client-side usage:

1import { UploadcareAuthSchema } from '@uploadcare/rest-client'
2
3const authSchema = new UploadcareAuthSchema({
4  publicKey: 'YOUR_PUBLIC_KEY',
5  signatureResolver: async (signString) => {
6    const response = await fetch(`/sign-request?signString=${encodeURIComponent(signString)}`)
7    return response.text()
8  }
9})

Pagination

Use the paginate helper to iterate through all pages of results:

1import { listOfFiles, paginate } from '@uploadcare/rest-client'
2
3const pages = paginate(listOfFiles)({}, { authSchema })
4for await (const page of pages) {
5  console.log(page)
6}

File conversion

Convert video and document files using the unified convert API:

1import { convert, conversionJobStatus, ConversionType } from '@uploadcare/rest-client'
2
3// Video conversion
4await convert(
5  { type: ConversionType.VIDEO, paths: [':uuid/video/-/size/x720/'], store: false },
6  { authSchema }
7)
8
9// Document conversion
10await convert(
11  { type: ConversionType.DOCUMENT, paths: [':uuid/document/-/format/pdf/'], store: false },
12  { authSchema }
13)
14
15// Check conversion job status
16await conversionJobStatus(
17  { type: ConversionType.VIDEO, token: 12345 },
18  { authSchema }
19)

Full documentation

Read the full documentation on JS API clients GitHub.