Uploading files

Projects

All files are uploaded into the projects. Projects are separate environments with unique sets of API keys, dedicated storage, and settings.

For example, projects can be used to separate development, staging and production environments. Learn more about projects.

Note: Image uploads are available on the Demo plan. To upload other file types, you must add a credit card to your account according to "Know your customer" (KYC) principles, but as long as you stay on the free plan, you won't be charged.

Upload API request and response

When you upload a file,

import { uploadDirect } from '@uploadcare/upload-client'

// fileData must be `Blob` or `File` or `Buffer`
const result = await uploadDirect(
  fileData,
  {
    publicKey: 'YOUR_PUBLIC_KEY',
    store: 'auto',
  }
)javascript

you immediately receive the file's UUID in a 200 response,

{
  "sample-image.jpeg": "17be4678-dab7-4bc7-8753-28914a22960a"
}

and the file immediately becomes available on our CDN.

https://ucarecdn.com/17be4678-dab7-4bc7-8753-28914a22960a/

Save this UUID into your database and retrieve it to:

• Serve optimized and transformed images.
• Encode videos based on their size and codec.
• Organize them with arbitrary metadata.
• Detect the type of content.

File storing behavior

When uploading files, you can specify whether you want to keep them permanently or not.

Notice the UPLOADCARE_STORE parameter in the example above. It can be set as follows:

• 0 — the file will be deleted after 24 hours. If no value is provided, 0 is used as the default.
• 1 — the file will be stored permanently until explicitly deleted.
• auto — defers the choice of storage behavior to the project's auto-store setting (which is ON by default).

Use this parameter to fine-tune the storage behavior. When unsure, it's recommended to use auto and control the storage behavior through project settings. Our official libraries default to auto.

Learn more about storage.

Information about uploaded files

We can extract file data that you can use: from basic file information, e.g. EXIF, to insights into its content. We can automatically analyze files for things like malware or NSFW content. It also allows you to use MIME type moderation.

Check out files section in Dashboard to see it in action.

Uploading from the browser

If you need to build your own uploading solution and don't want to use File Uploader, one of the options is to use our JS SDK. Upload Client works with both Node.js and browsers.

Uploading widgets for iOS and Android

Both Swift and Kotlin integrations have not only uploaded API methods but include uploading widgets for iOS and Android. They allow to:

• Upload files from a local disk, camera, and cloud sources.
• Upload multiple files at once.
• Track, pause and continue multipart uploading.
• Upload in the background.

Upload local file

The simplest way to upload a local file is to perform a HTTP POST request. As in the example above, you only need to specify the project's public key. Direct file uploads support files smaller than 100 MiB only. (If you want to upload larger files, please use multipart uploads instead).

import { uploadDirect } from '@uploadcare/upload-client'

// fileData must be `Blob` or `File` or `Buffer`
const result = await uploadDirect(
  fileData,
  {
    publicKey: 'YOUR_PUBLIC_KEY',
    store: 'auto',
  }
)javascript

Check out detailed API reference for direct uploads.

Upload from URL

Uploadcare can fetch a file from a publicly available URL and upload it to your project.

import { uploadFromUrl } from '@uploadcare/upload-client'

const result = await uploadFromUrl(
  'https://source.unsplash.com/featured',
  {
    publicKey: 'YOUR_PUBLIC_KEY',
  }
)javascript

Check out detailed uploads from URL API reference.

Requests to the endpoint return a JSON dictionary with a token that can be further used to check the status of an upload request. The token is not a file ID and can't be used to address the file directly. The actual file ID should be retrieved by calling the /from_url/status/ endpoint. Integration implementation may vary, please refer to the respective documentation.

import { fromUrlStatus } from '@uploadcare/upload-client'

const result = await fromUrlStatus(
  'token',
  {
    publicKey: 'YOUR_PUBLIC_KEY'
  }
)javascript

Check out detailed API reference for uploads from URL.

import { uploadFromUrl } from '@uploadcare/upload-client'

const result = await uploadFromUrl(
  'https://source.unsplash.com/featured',
  {
    publicKey: 'YOUR_PUBLIC_KEY',
    checkForUrlDuplicates: 1,
  }
)javascript

Upload large file

Multipart uploads should be used if you need to upload files larger than 100 MiB or if you want to explicitly trigger AWS S3 Transfer Acceleration.

import { uploadMultipart } from '@uploadcare/upload-client'

// fileData must be `Blob` or `File` or `Buffer`
const result = await uploadMultipart(
  fileData,
  {
    publicKey: 'YOUR_PUBLIC_KEY',
    store: 'auto',
    fileName: 'large-file.mp4',
    contentType: 'video/mp4',
  }
)javascript

Check out detailed API reference for multipart uploads.

Note: Each uploaded part should be at least 5242880 bytes in size except for the last one, which can be smaller. You can upload the file parts in parallel, provided that the byte order stays unchanged.

Add arbitrary metadata

You can add additional, arbitrary key-value data associated with uploaded files. For example, you could store user IDs, order IDs, or tags.

import { uploadDirect } from '@uploadcare/upload-client'

// fileData must be `Blob` or `File` or `Buffer`
const result = await uploadDirect(
  fileData,
  {
    publicKey: 'YOUR_PUBLIC_KEY',
    store: 'auto',
    metadata: {
      userID: '1',
      type: 'avatar'
    }
  }
)javascript

Learn more about file metadata.

Signed uploads

Signed upload requests include an authentication signature that is generated based on your project's secret key and expiration time parameters. This signature must be generated on your backend, as you must never expose your secret key in client-side code. Learn more about signed uploads.

Webhooks on upload

Uploadcare can notify your application when a new file has been uploaded asynchronously. For example, you may need to decide on your file based on the abovementioned analysis. When an upload happens, we'll make a POST request with a JSON payload to the endpoint you provided. Learn more about webhooks.

Get file info

There're various methods to get file information: via Upload API, REST API, or URL API. Upload API gives you limited but essential access, while REST API gives full details. Integration implementation may vary, please refer to the respective documentation.

import { info } from '@uploadcare/upload-client'

const result = await info(
  'UUID',
  {
    publicKey: 'YOUR_PUBLIC_KEY'
  }
)javascript

Check out detailed API reference for file info.