Transloadit

What are Assembly Instructions?

Transloadit Assembly Instructions define the named Steps in a file-processing workflow. Each Step selects a Robot and its parameters; the use parameter determines how uploaded, imported, or generated files flow between Steps.

How Assembly Instructions work

Instructions form a directed, acyclic processing graph expressed as named Step configurations and their input relationships. Each Step selects a Robot and parameters, while use determines which uploads or prior results flow into it. Steps that import or generate files can omit use when they do not depend on an earlier Step. Other Steps that omit use are implicitly connected to the preceding Step’s output; the first declared Step defaults to :original. Declare use explicitly when Step order should not determine the graph. The reserved Step name :original refers to uploaded files. A Step declared under that name may only run the /upload/handle Robot, and no other Step may run that Robot; a use value can reference :original without declaring it as a Step. The Instructions document is distinct from an Assembly, which is one execution of the graph, and from a Template, which persists Instructions for reuse. Before media processing begins, Transloadit validates that each Step is a well-formed object naming an existing Robot, that every declared use reference resolves, and that the graph contains no cycles.

Key facts

  1. Step names are graph identifiers. If use names a Step that does not exist, Transloadit rejects the Assembly with ASSEMBLY_STEP_UNKNOWN_USE (HTTP 400) before processing starts.
  2. One Step’s results can feed several later Steps, so derivatives do not each need their own upload or import. Those Steps run in parallel as soon as their input Step emits files, so with explicit use values the order in which Steps are declared does not set the order in which results are produced or exported. Declaration order matters only where a Step omits use and is implicitly connected to the preceding Step.
  3. A Template keeps reusable workflow logic out of client requests. Clients can override Steps by default; set allow_steps_override to false in the Template, and requests that still supply Steps are rejected with TEMPLATE_DENIES_STEPS_OVERRIDE (HTTP 400). The setting covers Steps only: other request parameters are still merged over the Template. To stop untrusted callers from changing those, require Signature Authentication (the Workspace setting, or require_signature_auth on the Template) and have a trusted back end sign only the parameters it approves. The requirement applies to requests authenticated with an Auth Key; valid bearer tokens bypass it. A signature covers only the serialized params. Upload form fields sent beside it are unsigned, fill ${fields.*}, and take precedence over same-named values in the signed fields key, so a locked Template that builds a storage path or another setting from ${fields.*} still lets the caller choose that value.
  4. A Step that produces nothing has not necessarily failed. By default a Robot ignores file types it does not handle (the documentation’s example is /video/encode ignoring images), so a branch can simply produce nothing for those files. Use /file/filter to route mixed uploads on purpose; the documentation reserves force_accept for debugging and edge cases.

When Assembly Instructions matter

Save Instructions in a Template when callers should reuse a server-managed workflow. If callers must not alter its Steps, set allow_steps_override to false; to keep them from changing other request parameters as well, require Signature Authentication for requests made with your Auth Key. Neither control covers upload form fields, so do not derive a setting that callers must not choose from ${fields.*}. When generating Instructions or renaming Steps, check that every use value references a declared Step name or :original so the Assembly passes validation.

How Transloadit helps with Assembly Instructions

Transloadit validates and executes Assembly Instructions as the workflow for an Assembly. Each named Step invokes one Robot to upload, import, process, analyze, store, or serve files, and the use parameter routes results between Steps. A Template stores Instructions for reuse, an Assembly is one execution of them, and Assembly Status and Notifications report the outcome.

Explore Transloadit’s platform capabilities

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