How to Integrate Uploadcare with Your Headless CMS

What is Uploadcare?

Uploadcare is a file uploading, image processing, and CDN delivery platform for teams that handle media-heavy web and app experiences. It provides a File Uploader, Upload API, REST API, image transformations, adaptive delivery, and CDN URLs for images, videos, PDFs, and other files. Teams use it when they need browser uploads, remote URL uploads, responsive images, and media processing without building a file pipeline from scratch.

Why integrate Uploadcare with a headless CMS?

Media workflows get messy fast when content and files live in different places. An editor publishes a product page in one system, downloads an image from another, resizes it in a desktop tool, uploads it to a CDN, then pastes the final URL back into the entry. That works for 10 assets. It breaks when you have 10,000 product images, localized campaign files, partner-submitted PDFs, and multiple frontends that all need different sizes and formats.

Connecting Uploadcare to a headless CMS fixes the handoff. Your content entry can keep the business meaning, like product name, locale, category, author, campaign, and publish status, while Uploadcare handles file upload, transformation, storage, and delivery. Instead of asking editors to remember naming rules or transformation URLs, the integration can create or update Uploadcare files when content changes and store the Uploadcare UUID or CDN URL back on the document.

A headless CMS gives you API access, but structured content and real-time events make the difference. With Sanity's AI Content Operating System, content is typed JSON in the Content Lake, so your integration can query exactly the image, alt text, slug, locale, and related product data Uploadcare needs. Webhooks or Functions can run on publish, update, or delete events, which means you don't need nightly batch jobs or manual media audits just to keep files in sync.

Architecture overview

A typical Uploadcare and Sanity integration starts when an editor publishes or updates a document in Sanity Studio. Sanity writes the structured document to the Content Lake, then a webhook fires on the publish event. The webhook can call your API route, or you can run the same logic in a Sanity Function so the sync runs server-side without a separate queue, cron job, or hosting layer. The handler receives the document ID, then uses @sanity/client and a GROQ query to fetch only the fields Uploadcare needs. For example, a product sync might fetch the product title, slug, locale, main image asset URL, alt text, and referenced brand name in one query. The handler downloads the Sanity asset URL, sends the file bytes or remote URL to Uploadcare using @uploadcare/upload-client or the Upload API, sets store to auto, and optionally attaches metadata such as the Sanity document ID and locale. Uploadcare returns a file UUID. Your sync can patch that UUID and the CDN base URL back into the Sanity document, for example uploadcare.uuid and uploadcare.cdnUrl. The frontend then renders Uploadcare URLs with transformations such as /-/resize/800x/, /-/format/auto/, or /-/quality/smart/. The end user gets the right image size and format from Uploadcare's CDN, while editors keep working in Sanity Studio.

Common use cases

Step-by-step integration

1. 1

   Create your Uploadcare project

   Sign up for Uploadcare, create or open a project, and copy the public key from the Uploadcare dashboard. If your sync needs REST operations such as file deletion or storage changes, also create a secret key and keep it server-side only.

2. 2

   Install the SDKs

   Install the Uploadcare upload client and Sanity client in the service that will receive webhooks: npm install @uploadcare/upload-client @sanity/client. Add UPLOADCARE_PUBLIC_KEY, SANITY_PROJECT_ID, SANITY_DATASET, and a Sanity token with read and patch permissions to your environment.

3. 3

   Model Uploadcare fields in Sanity Studio

   Add fields for the original Sanity asset and the Uploadcare result. A common pattern is mainImage for the editor-selected source asset, alt for accessibility text, and an uploadcare object with uuid, cdnUrl, syncedAt, and status fields.

4. 4

   Create the sync trigger

   Create a Sanity webhook that fires on publish events for the document types that contain media, such as product, article, or campaign. Use a GROQ filter like _type == "product" && defined(mainImage.asset). Point it to your API route, or run equivalent logic in a Sanity Function.

5. 5

   Upload the file to Uploadcare

   In the handler, fetch the document from Sanity with GROQ, download the Sanity asset URL, and send the bytes to Uploadcare with uploadFile. Store the returned UUID and CDN URL back on the Sanity document so your frontend doesn't need to repeat the sync work.

6. 6

   Test the frontend output

   Publish one test entry, confirm the Uploadcare UUID appears in Sanity Studio, then render a transformed CDN URL such as https://ucarecdn.com/{uuid}/-/resize/1200x/-/format/auto/. Test missing images, draft updates, deleted files, and republished content before you roll it out.

Code example

import {createClient} from '@sanity/client'
import {uploadFile} from '@uploadcare/upload-client'

const sanity = createClient({
  projectId: process.env.SANITY_PROJECT_ID!,
  dataset: process.env.SANITY_DATASET!,
  apiVersion: '2025-01-01',
  token: process.env.SANITY_TOKEN!,
  useCdn: false,
})

export async function POST(req: Request) {
  const {_id} = await req.json()

  const doc = await sanity.fetch(
    `*[_id == $id][0]{
      _id,
      title,
      "assetUrl": mainImage.asset->url
    }`,
    {id: _id.replace(/^drafts\./, '')}
  )

  if (!doc?.assetUrl) return Response.json({skipped: true})

  const asset = await fetch(doc.assetUrl)
  const buffer = Buffer.from(await asset.arrayBuffer())

  const file = await uploadFile(buffer, {
    publicKey: process.env.UPLOADCARE_PUBLIC_KEY!,
    store: 'auto',
    fileName: `${doc._id}.jpg`,
    metadata: {sanityDocumentId: doc._id, title: doc.title || ''},
  })

  await sanity.patch(doc._id).set({
    uploadcare: {
      uuid: file.uuid,
      cdnUrl: `https://ucarecdn.com/${file.uuid}/`,
      syncedAt: new Date().toISOString(),
    },
  }).commit()

  return Response.json({uuid: file.uuid})
}

How Sanity + Uploadcare works

CMS approaches to Uploadcare

Keep building

Explore related integrations to complete your content stack.