How to accept large uploads that survive a dropped connection

Two upload paths, and only one of them resumes

Transloadit accepts files in two ways, and the difference between them only shows up on a bad connection. Files can be attached to the multipart/form-data POST that creates the Assembly, which is simple and fine for a profile picture. Any interruption to that request fails the upload and the Assembly with it, and the client has no way to continue: it can only send everything again.

The other path uses [tus](https://tus.io), an open protocol for resumable uploads over HTTP with client implementations in most languages. Transloadit runs a tus server, and a client that speaks the protocol can pause, lose its connection, and pick up from the byte the server last acknowledged. For anything measured in hundreds of megabytes, that is the difference between an upload that eventually completes and one that never does.

Declare how many files are coming

A resumable upload inverts the usual order: the Assembly is created before any bytes exist. The creation request carries params as normal, plus a num_expected_upload_files field stating how many files will follow, and no file content at all. The response is an ordinary Assembly Status with two additions that matter here, tus_url for where the uploads go and the trio of expected_tus_uploads, started_tus_uploads, and finished_tus_uploads for tracking them.

That declared count is enforced more strictly than it first appears. The Assembly stays in ASSEMBLY_UPLOADING until every expected upload has finished, even when files that arrived early have already been processed. Uploads offered beyond the declared count are dropped without an error, which makes a wrong count one of the harder bugs to notice: the Assembly succeeds, and a file is simply missing from the results.

POST /assemblies HTTP/1.1
Host: api2.transloadit.com
Content-Type: multipart/form-data; boundary=---xyz

-----xyz
Content-Disposition: form-data; name="params"

{"auth":{"key":"YOUR_KEY"},
 "template_id":"YOUR_TEMPLATE_ID"}
-----xyz
Content-Disposition: form-data;
  name="num_expected_upload_files"

2
-----xyz--

Resuming is an offset, not a retry

Each upload begins with a POST to the tus_url that creates a resource rather than sending data. The request carries three pieces of metadata, assembly_url, filename, and fieldname, and the server replies with an upload URL in the Location header. The bytes then go to that URL in one or more PATCH requests, and once the last one lands the file is fed into the Assembly without any further call.

Recovery uses the same URL. A HEAD request returns an Upload-Offset header with the number of bytes the server actually holds, and the client resumes with a PATCH starting from exactly that offset. This is why a retry and a resume are not the same operation: a retry sends the file again from zero, while a resume asks the server what it already has and sends only the difference.

HEAD /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0

HTTP/1.1 204 No Content
Upload-Offset: 3000
Upload-Length: 10000

PATCH /resumable/files/136058f2ef4d HTTP/1.1
Host: api2-freja.transloadit.com
Tus-Resumable: 1.0.0
Upload-Offset: 3000
Content-Length: 7000
Content-Type: application/offset+octet-stream

The transfer resumes, the Assembly still expires

Resumability is often read as an unlimited grace period, and it is not. The Assembly was created at the start, and its clock is already running: uploading is limited to eight hours, processing to a further eight, and the two together are capped at sixteen hours from creation. An Assembly that passes those limits returns ASSEMBLY_EXPIRED, and the partial upload behind it stops being useful.

This matters most for the workloads that need resumability in the first place. A user who pauses a large upload overnight will come back to an Assembly that no longer exists, so the client needs to detect that case and create a new one rather than retrying into a dead URL. Treating expiry as an expected outcome, instead of an error to log, keeps that recovery path honest.

Attach the metadata each file needs

Beyond the three required values, any additional metadata sent with an upload becomes available as an Assembly Variable under file.user_meta, so a key sent as owner is read as ${file.user_meta.owner}. That distinction is worth internalising early, because fields is shared by every file in the Assembly while user metadata belongs to one file. A batch where each file needs its own destination path, owner, or category wants the latter, and trying to express it through shared fields ends in a Template that cannot tell the files apart.

For branching on content rather than on what the client claimed, prefer ${file.mime} and match families such as image/* or video/*. A client-supplied filename or category is a hint, and treating it as a fact is how an executable ends up on a path that assumed images. The broad ${file.type} category exists as well, but MIME matching is the more precise of the two.

Sign the request when the browser is the client

An upload that starts in a browser means the Assembly Instructions are being submitted from an environment you do not control. Signature Authentication closes that gap: your back end signs the params with the Auth Secret, adds an auth.expires timestamp in the near future, and hands the result to the front end. Turning on the requirement in Workspace Settings makes the API reject anything unsigned for the account.

The useful part is that your server decides what it is willing to sign. It can refuse anonymous users, cap the Template a request may invoke, or narrow the parameters before signing, all with ordinary application logic. The Auth Secret never leaves the back end, and an intercepted signature is only good until the expiry it was issued with.

const uppy = new Uppy().use(Transloadit, {
  waitForEncoding: true,
  assemblyOptions: async () => {
    // Your back end signs with the Auth Secret
    const res = await fetch('/api/tl-signature')
    const { params, signature } = await res.json()
    return { params, signature }
  },
})

Frequently asked questions