Skip to navigation
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:

import { UploadClient } from '@uploadcare/upload-client'
const 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:

client
  .uploadFile(fileData)
  .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:

import { generateSecureSignature } from '@uploadcare/signed-uploads'
// Option A: expiration as timestamp in milliseconds
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
  expire: Date.now() + 60 * 30 * 1000 // 30 minutes from now
})
// Option B: expiration as a Date object
const { secureSignature, secureExpire } = generateSecureSignature('YOUR_SECRET_KEY', {
  expire: new Date("2099-01-01")
})
const client = new UploadClient({
  publicKey: 'YOUR_PUBLIC_KEY',
  secureSignature,
  secureExpire,
})

Bulk uploads

Use Queue to control concurrency when uploading multiple files:

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

Error handling

import { UploadError, NetworkError } from '@uploadcare/upload-client'
try {
  const file = await client.uploadFile(fileData)
} catch (error) {
  if (error instanceof NetworkError) {
    console.error('Network error:', error.message)
  } else if (error instanceof UploadError) {
    console.error('Upload error:', error.message)
  }
}

Authentication

For server-side usage, use UploadcareSimpleAuthSchema:

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

Warning: 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:

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

Pagination

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

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

File conversion

Convert video and document files using the unified convert API:

import { convert, conversionJobStatus, ConversionType } from '@uploadcare/rest-client'
// Video conversion
await convert(
  { type: ConversionType.VIDEO, paths: [':uuid/video/-/size/x720/'], store: false },
  { authSchema }
)
// Document conversion
await convert(
  { type: ConversionType.DOCUMENT, paths: [':uuid/document/-/format/pdf/'], store: false },
  { authSchema }
)
// Check conversion job status
await conversionJobStatus(
  { type: ConversionType.VIDEO, token: 12345 },
  { authSchema }
)

Search files

import { searchFiles } from '@uploadcare/rest-client'
const response = await searchFiles({ query: 'invoice' }, { authSchema })
response.results.forEach((file) => console.log(file.uuid, file.originalFilename))

File tags

import { getTags, updateTags } from '@uploadcare/rest-client'
const { tags } = await getTags({ uuid: 'YOUR_FILE_UUID' }, { authSchema })
await updateTags({ uuid: 'YOUR_FILE_UUID', add: ['featured'], delete: ['draft'] }, { authSchema })

Full documentation

Read the full documentation on JS API clients GitHub.