File Upload API guide: architecture, security, and provider selection

Choosing a File Upload API is an architecture decision, not a widget comparison. The right design controls where bytes travel, who can authorize a transfer, how interrupted work resumes, when a file becomes trusted, where durable copies live, and how processing results return to the product.

What matters most

• Choose build, buy, or hybrid ownership by testing recovery, security, processing, and operational requirements—not only the happy-path demo.
• Use framework-specific examples only when their lifecycle, server authorization, and recovery behavior can be maintained and tested.

import Uppy from '@uppy/core'
import Transloadit from '@uppy/transloadit'

const uppy = new Uppy().use(Transloadit, {
  async assemblyOptions() {
    const response = await fetch('/api/transloadit-params', {
      credentials: 'same-origin',
    })
    if (!response.ok) {
      throw new Error('Could not authorize this upload')
    }
    return response.json()
  },
  waitForEncoding: true,
})

uppy.on('transloadit:complete', (assembly) => {
  console.log(assembly.assembly_id, assembly.results)
})

import { randomUUID } from 'node:crypto'
import { Transloadit } from 'transloadit'

function requiredEnvironmentValue(name: string): string {
  const value = process.env[name]
  if (value == null) throw new Error(`Missing environment variable: ${name}`)
  return value
}

const transloadit = new Transloadit({
  authKey: requiredEnvironmentValue('TRANSLOADIT_KEY'),
  authSecret: requiredEnvironmentValue('TRANSLOADIT_SECRET'),
})

export function createAuthorizedUploadParameters() {
  // Call this only after the server has authenticated the request and authorized the operation.
  return transloadit.calcSignature({
    auth: {
      expires: new Date(Date.now() + 5 * 60 * 1000).toISOString(),
      nonce: randomUUID(),
    },
    template_id: requiredEnvironmentValue('TRANSLOADIT_UPLOAD_TEMPLATE_ID'),
  })
}

{
  "allow_steps_override": false,
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "accepted_images": {
      "use": ":original",
      "robot": "/file/filter",
      "accepts": [
        ["${file.mime}", "regex", "^image/"]
      ],
      "error_on_decline": true
    },
    "preview": {
      "use": "accepted_images",
      "robot": "/image/resize",
      "resize_strategy": "fit",
      "width": 1600,
      "height": 1600
    },
    "exported": {
      "use": ["accepted_images", "preview"],
      "robot": "/s3/store",
      "credentials": "my_s3_credentials",
      "path": "uploads/${file.id}/${file.url_name}"
    }
  }
}

Technical details worth knowing

• A browser-to-application upload makes the application server part of the data path, while a direct-storage or direct-processing design keeps file bytes out of that request handler.
• The tus core protocol resumes by reading the server’s Upload-Offset with HEAD and continuing with PATCH; sending the whole file again is a retry, not a resume.
• Uppy’s Transloadit plugin uses tus for file transfer and can request signed Assembly parameters from an application back end through its assemblyOptions function.
• Transloadit Signature Authentication signs the JSON-encoded parameters with the Auth Secret on a trusted server; the secret itself must never be sent to browser code.
• A saved Template with allow_steps_override set to false prevents an untrusted client from replacing its Steps or selecting a different storage target through Step overrides.
• Without an export Robot, Transloadit deletes temporary files after 24 hours, while their temporary URLs can expire after a few hours and are intended only for limited, short-term retrieval.
• For Transloadit tus uploads, the Assembly is created before file bytes arrive and remains in ASSEMBLY_UPLOADING until the declared uploads have finished.
• The Transloadit upload window is eight hours from Assembly creation, so a resumable client still needs a deliberate restart path when the Assembly has expired.

A practical approach

When Transloadit is useful

Use Transloadit when uploads need tus resumability, Uppy browser UX, remote-source ingestion, multi-step file processing, or exports to storage you control. Exact parameter contracts live in the /upload/handle, /file/filter, /image/resize, and /s3/store Robot documentation.

Architecture boundary

Transloadit can receive files, run asynchronous processing workflows, and export results, but your application still owns user authentication, tenant authorization, the durable asset record, publication policy, and delivery from permanent storage.