> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://uploadcare.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://uploadcare.com/docs/_mcp/server.

# JS API clients

> JS Uploadcare API Clients

JS API clients handle uploads and file operations by wrapping Uploadcare
[Upload API](https://uploadcare.com/docs/api/upload/) and [REST API](https://uploadcare.com/docs/api/rest/).
You can use it from within your Node.js app and in a browser.

[JS API clients GitHub →](https://github.com/uploadcare/uploadcare-js-api-clients)

## Features

Uploading ([Upload API](https://uploadcare.com/docs/api/upload/)):

* 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](https://uploadcare.com/docs/api/rest/)):

* 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](https://uploadcare.com/docs/api/url/)):

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

## Requirements

Node.js 16 or later.

## Install

```bash
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:

```javascript
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:

```javascript
client
  .uploadFile(fileData)
  .then(file => console.log(file.uuid))
```

> **Note**
>
> **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:

```javascript
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:

```javascript
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

```javascript
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`:

```javascript
import { UploadcareSimpleAuthSchema } from '@uploadcare/rest-client'

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

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

```javascript
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:

```javascript
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:

```javascript
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

```javascript
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

```javascript
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](https://github.com/uploadcare/uploadcare-js-api-clients).

## Related guides

* [File Uploader](/docs/file-uploader/)
* [jQuery File Uploader](/docs/uploads/file-uploader/)