Migrate from Uploadcare to Transloadit

Uploadcare offers upload, management, and URL APIs⁠, including CDN delivery and file groups⁠. Transloadit separates these concerns into upload/import Robots, processing Robots, export Robots, and optional CDN delivery. Inventory the operations you use and map supported processing tasks to Steps in a Transloadit Template; this is not a one-to-one replacement for every Uploadcare feature.

You can choose Transloadit Storage (currently in beta) for hosted files, or bring your own storage. With Transloadit Storage, a separate storage account is optional. The File Library (preview) offers digital asset management for browsing, organizing, previewing, and downloading files in Transloadit Storage. File Library access is enabled per Workspace; ask us about availability.

The executable workflow below demonstrates the bring-your-own-storage option. It moves uploads and processing to Templates and exports files to your bucket. Migrating existing asset folders and metadata, switching delivery URLs, and replacing asset pickers or CMS/editor integrations require a separate migration plan; they are not implemented by the examples below.

Migration map

Use Step dependencies to route files between processing tasks, not to replace persistent file-group records. Sign Smart CDN URLs on your backend and use a separate compatible Template for on-demand delivery.

Transformation decisions. Inventory complete URL-operation chains, application presets, crop coordinates, orientation, dimensions, quality, and format. Uploadcare’s format/auto⁠ selects formats using the browser’s capabilities; the fixed WebP avatar below does not reproduce that negotiation. Compare outputs on representative images, including transparency and animation. Video conversions need their own Templates; neither example below migrates video streaming, document conversion, every URL operation, or custom uploader plugins.

Moderation is a separate workflow. Uploadcare’s unsafe-content moderation⁠ can scan images on upload or through an asynchronous REST add-on, with results in appdata. Preserve the moderation outcome and policy, including thresholds and deletion/review decisions, in your migration inventory. These examples optimize or preview files; they do not recreate that moderation gate. Choose and validate a replacement before publishing UGC, and keep the existing gate until it is ready. MIME filtering, malware scanning, and inappropriate-content detection address different problems.

Replace the upload widget

For browser uploads, use Uppy with the Transloadit Plugin. Uppy gives you a file picker, drag-and-drop UI, resumable uploads, remote sources, and direct Transloadit integration.

A typical Uploadcare flow where users upload an image and receive transformed CDN URLs becomes:

1. The browser uploads through Uppy and references a saved Transloadit Template.
2. The Template creates all variants your app needs.
3. Transloadit notifies your backend with the result URLs.
4. Your backend stores those URLs in your database.

Configure a notify_url in the signed Assembly request and verify incoming notification signatures. For browser-side completion, enable Uppy’s waitForEncoding; the default only waits for the upload.

Rewrite callbacks that expect Uploadcare UUIDs, group IDs, or CDN-operation URLs. Keep your own asset ID and associate it with the completed Assembly and exported files. Test local and remote sources, resuming, cancellation, validation, and failures; replacing the upload UI does not replace an existing asset browser or CMS integration.

Uploadcare’s webhooks⁠ cover upload, file-information, storage, and deletion events. Its optional signing secret produces an X-Uc-Signature header, and failed deliveries are retried. Map processing completion to Assembly Notifications, handle catalog and deletion events in your application, and use Transloadit’s own notification verification. Make updates idempotent by Assembly ID and require successful export before publishing. Test retry and reconciliation behavior rather than carrying over the old event payload or retry schedule.

Security decisions. Uploadcare’s signed uploads⁠ authorize ingestion; signed delivery⁠ separately restricts access through a secure CDN subdomain or configured custom domain. Inventory public and private paths, token expiry, and allowed variants. Use backend-signed Transloadit requests for the allowed Templates and fields, then enforce download authorization through your bucket/CDN. A signed Assembly request does not grant or restrict access to an exported S3 object. Do not make private files public to simplify the migration. If you use Uploadcare malware protection⁠, add and test an explicit scan Step and a quarantine/publication gate; the printed Templates do not scan files. Full ACL implementation, compliance qualification, and regional routing are outside this guide’s examples.

Example Template

This Template receives an image upload, creates a square WebP avatar, optimizes both the original and the avatar, and stores the optimized files on S3. Optimization has no format parameter and, with progressive left disabled as here, returns the original if the optimized file is larger. Enabling progressive allows an optimization result to be retained even if it is larger:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "avatar": {
      "use": ":original",
      "robot": "/image/resize",
      "width": 512,
      "height": 512,
      "resize_strategy": "fillcrop",
      "format": "webp"
    },
    "optimized_original": {
      "use": ":original",
      "robot": "/image/optimize",
      "result": true
    },
    "optimized_avatar": {
      "use": "avatar",
      "robot": "/image/optimize",
      "result": true
    },
    "exported": {
      "use": ["optimized_original", "optimized_avatar"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploads/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

Set up Third-party Credentials for S3 and configure your CDN to serve the bucket root with read access. url_prefix does not create a CDN or grant access. acl: "bucket-default" sends no object ACL; configure access through your bucket policy and CDN origin access. After ASSEMBLY_COMPLETED, read the original from results.optimized_original and the avatar from results.optimized_avatar. Persist only entries with is_temp_url: false: export updates the producing Step’s URLs. Temporary Transloadit URLs expire after 24 hours; see saving conversion results.

Import existing Uploadcare files

Inventory originals and catalog data. Enumerate your application’s referenced UUIDs and reconcile them with the project’s REST API file inventory⁠, following pagination. File info⁠ includes original_file_url, original_filename, file size, storage status, and processing data. Select the authorized original download for each file; if original_file_url is absent or the file was removed, resolve that gap before migrating its record. Obtain fresh signed source URLs on your backend when required.

Preserve arbitrary metadata⁠, tags⁠, and relevant appdata in your database or sidecar records; importing bytes does not copy them. File groups⁠ are immutable collections with indexed members, and a member can include a transformation recipe. Record the group ID, ordered member UUIDs, and recipes separately. An Assembly processes files but does not recreate that persistent collection. Preserve folder paths, other collection relationships, and revision history maintained by your application, assigning distinct storage keys to revisions; these Templates neither discover nor export historical revisions or application-only relationships.

If you already have authorized Uploadcare download URLs in your inventory, import them with 🤖/http/import:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.uploadcare_url}"
    },
    "preview": {
      "use": "imported",
      "robot": "/file/preview",
      "result": true
    },
    "exported": {
      "use": ["imported", "preview"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "uploadcare-import/${unique_prefix}/${file.url_name}",
      "acl": "bucket-default"
    }
  }
}

The preview Step uses 🤖/file/preview (beta); it may return a generic file-type icon when a content thumbnail is unavailable. Select authorized uploadcare_url values on your backend. Importing a transformed CDN URL copies that rendition, not necessarily the original. You can backfill only referenced files or pass an array of authorized URLs to /http/import for a bounded batch. Keep an old-ID-to-new-location mapping and verify delivery access and output quality before switching reads. This import Template returns exported files under results.imported and results.preview. Private S3 objects need an authorized download or your configured CDN.

Checklist

Delivery cutover. Record a mapping from each UUID and used operation chain to its verified destination. Replace URLs in application records, rendered pages, srcset, CSS, email, and CMS content; appending Uploadcare’s operation syntax to a new storage hostname does not apply it. Use redirects only on a domain or application route you control, with a resolver for the old paths and the intended access rules. For provider-owned CDN URLs, update references you control and retain source access during the overlap period. Test authorization, caching, and real pages before making redirects permanent or deleting source files.

Planning estimate. For one uploader, a few image variants, an accessible inventory, and an existing bucket/CDN, allow several engineering days for a tested pilot, followed by measured backfill time. Private delivery, groups, moderation, CMS changes, and revision/catalog exports can require weeks or more. This is an engineering planning estimate, not a measured migration benchmark. Measure import, processing, and export throughput and cost on a representative batch, including source downloads, destination delivery, and the period running both services.

1. Inventory originals, metadata, tags, group order/recipes, revisions, access rules, operations, uploader callbacks, and moderation outcomes. Resolve excluded features before cutover.
2. Version the Template Instructions in your repository and test the required variants and gates. Retain Template revisions, Assembly IDs, failures, and destination mappings for support.
3. Configure credentials, storage/CDN access, signing, and the notification receiver. Verify durable delivery and duplicate/failure handling in a pilot.
4. Set bounded batch sizes, concurrency, retry limits, and a migration budget. Confirm processing and storage regions, retention, and compliance requirements before moving data.
5. Switch new uploads behind a feature flag, backfill in bounded batches, and reconcile partial exports before retries. Compare originals, derivatives, catalog counts, and private access.
6. Update reads and delivery references in cohorts, retaining the source mapping for rollback. Reconcile the final source delta and keep old delivery available until the rollback window and cache lifetimes have passed.