Transloadit

What is an Assembly?

A Transloadit Assembly is one execution of Assembly Instructions on files that are uploaded, imported, or generated by the workflow itself. Each execution has a unique assembly_id that identifies it in later API requests.

How Assemblies work

An Assembly is the runtime workflow created when a request combines Assembly Instructions with input sources: uploaded files, files fetched by import Steps, or files that a Robot creates itself, such as a website screenshot or an image generated from a text prompt. The Instructions arrive inline as steps or by reference to a saved Template through template_id; the Template stores configuration, while the Assembly is one particular run of it. Steps start as soon as the Steps they depend on emit files, so one source file can feed several branches that execute in parallel. Transloadit reports the run through a single Assembly Status document, which is returned when the Assembly is created, served at its status URL, and sent to the notify_url if one is set. That document changes while the Assembly is uploading or executing; once the run reaches a terminal state it carries either ok with the final state or error with an error code.

Key facts

  1. A successful HTTP response to the creation request means the Assembly was accepted, not that processing succeeded. The Assembly is still running while ok is ASSEMBLY_UPLOADING, ASSEMBLY_EXECUTING, or ASSEMBLY_REPLAYING; only ASSEMBLY_COMPLETED means success. ASSEMBLY_CANCELED and REQUEST_ABORTED also appear under ok without being successful, and a status request can return HTTP 200 while the body carries an error, so branch on the body, not on the HTTP status.
  2. The assembly_id works as an access capability: anyone who knows it can request the Assembly Status, including submitted fields and results, without further authentication. Keep the ID and the status URLs out of public pages and anything shared with untrusted parties. The quiet option only shortens the creation response; it does not restrict who can read the status afterward.
  3. Creating an Assembly is not idempotent. Retrying the creation request, for example after a timeout, can start a second Assembly with its own assembly_id, and adding a signature nonce does not prevent that. Deduplicate retries in your application.
  4. Result files are grouped under the name of the Step that produced them, not in upload order, and one upload can yield several results; match them to uploads through original_id. Steps that only store files add no entry, and after an error the results can be partial. Result URLs on Transloadit’s temporary storage expire, so add an export Step when the files must be kept.

When Assemblies matter

Store the assembly_id on your server when a workflow must poll status, collect results, or match an incoming Notification to the request that started it, and treat it as a secret, because the ID alone is enough to read the Assembly Status. Decide before launch how your application learns the outcome, by polling the status URL or by setting a notify_url, because the response to the creation request only confirms that the Assembly was accepted.

Sources

Turn media knowledge into a working pipeline

Connect uploads, processing, AI, storage, and delivery through one declarative API — with the encoding stack, scaling, and format churn handled for you.

Try Transloadit for free