For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Dashboard
GuidesIntegrationsAPI ReferencesRelease notes
GuidesIntegrationsAPI ReferencesRelease notes
    • All integrations
  • Receiving files
    • Framework integrations
    • JavaScript File Uploader
    • React File Uploader
    • Angular File Uploader
    • Vue File Uploader
    • Svelte File Uploader
    • Next.js File Uploader
    • iOS
    • Android
    • CKEditor
    • TinyMCE
    • Redactor
    • Webflow
    • WordPress
    • Contentful CMS
    • JotForm
    • Marketo
  • Managing files
    • JavaScript SDK
    • PHP SDK
    • Python SDK
    • Ruby SDK
    • Rails SDK
    • Java SDK
    • Golang SDK
    • Rust SDK
    • Swift SDK
    • Kotlin SDK
    • Zapier
    • Make
    • Integrately
    • CLI
  • Delivering files
    • Adaptive image component
    • Next.js image loader
    • NuxtImage
  • From community
    • Shopify
    • Shopify (Debut theme)
    • WooCommerce
    • PHP Transformation URLs generation
    • Laravel Flysystem driver
    • Unpic Universal CDN URL translator
    • C# SDK
    • Erlang SDK
    • Elixir SDK
    • Flutter SDK
Dashboard
LogoLogo
On this page
  • Features
  • Requirements
  • Install
  • Usage examples
  • Signed uploads
  • Bulk uploads
  • Error handling
  • Authentication
  • Pagination
  • File conversion
  • Full documentation
  • Related guides
Managing files

JS API clients

Was this page helpful?
Previous

PHP API Client

Next
Built with

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.

Related guides

  • File Uploader
  • jQuery File Uploader