Migrate from Filestack to Transloadit

Filestack provides file picking, uploads, storage, and CDN transformations⁠ and asynchronous Workflows⁠. With Transloadit, Uppy handles browser picking and Robots handle file processing. Define a supported workflow in a Template, then use an SDK, Uppy, or the REST API to create Assemblies. Check the tasks your application uses individually; the mapping below does not promise complete feature parity.

This guide covers processing and exporting files to storage you control. It does not implement a hosted Transloadit DAM migration. Importing into a hosted Media Library, preserving its folders and metadata, delivery through tlcdn.com, migration dry runs and manifests, and Media Library roles, widgets, and CMS/editor integrations require a separate migration plan. The inventory described below is an application-owned migration record, not a hosted DAM migration tool.

Migration map

Filestack storage aliases expose existing external storage to its processing service without an upload through Filestack. If you already own the source bucket, decide whether originals can stay there while you process and export new derivatives. For Filestack-managed storage, download authorized originals through its CDN⁠ before retiring the account. This guide does not provide a bulk account-export or asset-discovery script.

Preserve the catalog separately. Before copying bytes, record your asset ID, Filestack handle, original download URL, storage location/container/path, filename, MIME type, size, checksum, and required derivatives. Filestack’s metadata endpoint⁠ can return file facts, storage information, and hashes; it generates that information on demand. Keep the source inventory and completed Assembly/export mapping in your own database.

Filestack Picker upload tags⁠ are returned in upload responses and webhooks. Its DAM⁠ also lets users edit asset tags and descriptions. Preserve those records separately from file metadata; the Templates below copy and process bytes, not catalog tags or descriptions. Use recorded storage paths to decide how destination object keys preserve folders; these examples generate new paths. Inventory any collections and revision relationships your application uses, including their order and permissions. Filestack’s overwrite operation⁠ replaces the file behind a handle, so a download is not a version-history export. This guide does not export collection membership or historical revisions; obtain those from your application or existing archive before switching if they are required.

Build a Template for each workflow

Translate transformation recipes. Filestack’s Processing Engine⁠ accepts tasks in CDN URLs, while its Workflows define tasks and conditional logic. Inventory the full task chain, parameters, named application presets, workflow IDs, and conditions used by each application view. Rebuild the required recipes as Templates, generate the derivatives, and compare representative images and documents for crop, aspect ratio, orientation, page selection, quality, and format. A thumbnail Robot does not replace the interactive Filestack Document Viewer⁠; choose a separate viewer if your application needs one. The examples below cover image/PDF previews and a generic file preview; they do not reproduce every Filestack transformation or intelligence task.

This Template checks the detected MIME type, creates an image thumbnail or a first-page PDF thumbnail, and stores accepted originals and previews. Other MIME types stop the Assembly with an error. This is type filtering, not malware scanning; add /file/virusscan if your workflow requires it:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_files": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^(image/[^/]+|application/pdf)$"]],
      "error_on_decline": true
    },
    "images": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "regex", "^image/"]]
    },
    "pdfs": {
      "use": "accepted_files",
      "robot": "/file/filter",
      "accepts": [["${file.mime}", "=", "application/pdf"]]
    },
    "image_thumb": {
      "use": "images",
      "robot": "/image/resize",
      "width": 600,
      "height": 600,
      "resize_strategy": "fit",
      "format": "webp",
      "result": true
    },
    "document_thumb": {
      "use": "pdfs",
      "robot": "/document/thumbs",
      "format": "jpg",
      "page": 1,
      "width": 600,
      "resize_strategy": "fit",
      "result": true
    },
    "exported": {
      "use": ["accepted_files", "image_thumb", "document_thumb"],
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "filestack-import/${unique_prefix}/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

The two routing filters use MIME types to keep images and PDFs on separate preview branches. Declined originals never enter the export Step. An Assembly is not a transaction: already exported accepted files are not rolled back if another file fails. Ignoring errors suppresses failures; it is not a substitute for routing or validation.

Track the storage objects written by each backfill attempt. Before retrying a failed Assembly, reconcile or delete its partial exports so retries do not leave duplicate or orphaned objects. Do not publish failed attempts in your application, even if some files were exported successfully.

Configure your CDN to read the bucket root; url_prefix only changes returned URLs. acl: "bucket-default" sends no object ACL; configure access through your bucket policy and CDN origin access. After ASSEMBLY_COMPLETED, read accepted originals from results.accepted_files and previews from results.image_thumb and results.document_thumb. Export adds or updates entries under the Steps named in its use parameter, unless that Step explicitly sets result: false. Persist only entries with is_temp_url: false. Temporary Transloadit URLs expire after 24 hours; see saving conversion results.

Replace file picking

For browser integrations, replace the Filestack picker with Uppy. Uppy can select local files, drag-and-drop uploads, and connect remote sources. The Transloadit Plugin sends files to an Assembly using your Template. Enable waitForEncoding to receive finished processing results in the browser, or set notify_url in your signed Assembly request and handle Assembly Notifications on your backend. Verify notification signatures and require successful completion before updating your database.

Filestack’s Picker response⁠ contains file handles, URLs, and upload metadata; onUploadDone reports uploaded and failed files. Rewrite handlers that expect that response shape, and test cancellation, retries, allowed file types/sizes, accessibility, and each remote-source authorization flow. Keep catalog tags on your backend and associate them with your asset ID rather than assuming picker metadata survives export.

Replace automation and security deliberately. Filestack webhooks⁠ have event-specific payloads and use FS-Timestamp and FS-Signature headers for verification. Its workflow job results are not an Assembly Status payload. Implement the Transloadit receiver using its own documented contract and signature scheme. Make database updates idempotent, retain the Assembly ID, and reconcile partial exports before retrying processing. Separate upload completion from successful processing and export before publishing an asset.

Filestack security policies⁠ use Base64URL policies signed with HMAC-SHA256 and can restrict expiry, calls, handles, upload paths/containers, and size. Upload and delivery authentication are configurable; inventory what your application actually enforces. Recreate upload authorization using Transloadit authentication on your backend, and configure download authorization with your storage/CDN. Existing Filestack policies and signatures do not authorize the replacement service. Never make private exports public just to replace a signed source URL. Filestack’s S3 upload access setting⁠ controls stored object access; review destination bucket policy, CDN origin access, and any signed-download scheme separately from Assembly authentication. The export examples set acl: "bucket-default"; verify the destination policy before migration.

Filestack’s Virus Detection⁠ runs asynchronously through Workflows after upload to storage. If you use it, design and test the replacement scan/quarantine gate before publishing originals or previews. Neither MIME filtering nor a successful upload proves that a file is safe.

Account for agent tooling. The Filestack Claude Plugin⁠ exposes tools for uploads, transformations, policy signing, workflow execution, and webhook verification. Inventory the actual URLs and workflows generated or invoked by those tools. Rebuild required operations with reviewed Template definitions and SDK/API calls; this guide does not offer a drop-in replacement for the plugin or its intelligence models. Keep Template revisions, Assembly IDs, output checks, and retry decisions for support and inspection. Estimate processing and storage costs for a sample batch, bound backfill concurrency and retries, and review regional data flows, retention, and compliance requirements before authorizing the full migration. This guide does not establish regulatory compliance or a regional-routing configuration.

Import existing Filestack URLs

Filestack CDN URLs⁠ identify files by handle. Select the authorized original URL, without transformation tasks, and provide a valid read policy/signature if source security requires one. Make its expiry long enough for the queued download, and keep signed source URLs out of logs and public manifests. If it resolves to a downloadable HTTPS URL, migrate it with 🤖/http/import:

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

Select authorized filestack_url values from your backend’s asset inventory. /file/preview is in beta and falls back to a generic file-type icon when it cannot generate a content thumbnail. Run bounded backfill jobs; /http/import also accepts an array of URLs. Keep source handles and URLs until the completed export’s access and quality are verified. Private S3 objects need an authorized download or your configured CDN. The import Template returns exported files under results.imported and results.preview.

Replace delivery URLs after verification. Keep a mapping from each old handle plus transformation recipe to its new exported URL. Verify original checksums, derivative appearance, MIME types, and authorized/public access before updating database records, rendered markup, CSS, CMS content, and API responses. Regenerate required derivatives instead of appending Filestack tasks to the new CDN hostname. Retain old records and a read-path switch for rollback while new uploads use the new path.

You can redirect URLs served from a domain you control. If you use Filestack’s custom CNAME⁠, replace its origin only after your delivery layer can resolve old handle/task paths and enforce the intended access rules. You cannot install your redirects on Filestack’s shared cdn.filestackcontent.com domain: replace those links in content you control and plan continued source access for references you cannot update. Test cache behavior and access controls before making redirects permanent.

Checklist

Planning estimate. For one picker, an accessible asset inventory, a few preview recipes, and a bucket you control, budget several engineering days for a tested pilot. A large backfill, custom domain compatibility, private delivery, document viewers, and application-owned catalog/version exports can take weeks or longer. These are planning estimates, not measured migration benchmarks; time a representative batch and include transfer limits, processing cost, validation, and rollback.

1. Inventory handles, storage paths, tags/descriptions, versions, picker callbacks, security rules, transformation recipes, workflow tasks, and agent-tool usage. Resolve any excluded feature before cutover.
2. Choose destination object keys, catalog storage, download authorization, CDN, and old-URL strategy. Configure Third-party Credentials with the needed access.
3. Build and verify Templates with representative images, PDFs, unsupported files, and failures. Include a scan/quarantine gate if required.
4. Replace the picker and webhook receiver in a pilot. Verify completion handling, signature checks, retries, idempotency, and private download access.
5. Run a bounded backfill; record completed exports and reconcile partial attempts. Compare original checksums and derivative quality before switching any asset’s read path.
6. Switch new uploads, reconcile the final source delta, then migrate reads in cohorts. Monitor errors, costs, and old-URL traffic; retain a rollback path and source access until sign-off.