# Create a new Assembly

POST`https://api2.transloadit.com/assemblies`

###### Warning

This endpoint requires your Auth Key to have the `assemblies:write` scope.

An Assembly can process and export files.[Assembly Instructions](/docs/topics/assembly-instructions.md) determine how we should process them. Instructions can be passed in directly (inside a `steps` parameter), or be saved in aTemplate (referred to in a `template_id` parameter). Templates allow you to re-use instructions, evolve them without deploying your app, and to not expose any secrets to where your app is deployed.

We accept `multipart/form-data` POST requests to accommodate regular `<form>` uploads to our service (as well as XHR / SDK usage).

Multiple files can be included as part of this request. If you want to perform resumable file uploads, the files are not included in this request as described in[Resumable Uploads](/docs/api/resumable-uploads.md).

###### Note

Transloadit supports file sizes up to 200 GB. If you require a higher limit for your application, please[get in touch](mailto:support@transloadit.com).

## POST fields

* Passing `signature` is optional. For more information, please check [Signature Authentication](/docs/api/authentication.md).
* Passing `params` is required. It should contain a JSON encoded object with the keys as shown in the table below.
* Passing `num_expected_upload_files` is optional. When using resumable uploads, it specifies the nunber of files that will be uploaded. More details are provided in [Resumable Uploads](/docs/api/resumable-uploads.md).

You can also supply other POST fields (that are not named `params`, `signature` or`num_expected_upload_files`) here. They can be used as variables to [make your Assembly Instructions dynamic](/docs/robots/file-filter.md#form-fields-in-instructions).

## Supported keys inside the `params` field

* ### `auth` — **required**

`object`\
Contains at least your Transloadit Auth Key in the `key` property.\
If you enable Signature Authentication, you must also set an expiry date for the request in the expires property:\
![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CoPVn8CkpFeWcaTxe6tAm4HNPmke)

```jsonc
{  
  "key": "23c96d084c744219a2ce156772ec3211",  
  "expires": "2009-08-28T01:02:03.000Z"  
}  
```

We strongly recommend including the `nonce` property — a randomly generated, unique value per request that prevents duplicate processing upon retries, can aid in debugging, and avoids attack vectors such as signature key reuse:\
![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CoPVn8CkpFeWcaTxe6tAm4HNPmke)

```jsonc
{  
  // …  
  "nonce": "04ac6cb6-df43-41fb-a7fd-e5dd711a64e1"  
}  
```

The `referer` property is a regular expression to match against the HTTP referer of this upload, such as `"example\.org"`. Specify this key to make sure that uploads only come from your domain.\
Uploads without a referer will always pass (as they are turned off for some browsers) making this useful in just a handful of use cases. For details about regular expressions, see [Mozilla's RegExp documentation](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global%5FObjects/RegExp).\
The `max_size` property can be used to set a maximum size that an upload can have in bytes, such as `1048576` (1 MB). Specify this to prevent users from uploading excessively large files.\
This can be set as part of the Assembly request or as part of the Template.\
The file size is checked as soon as the upload is started and if it exceeds the maximum size, the entire upload process is canceled and the Assembly will error out, even if it contains files that do not exceed the `max_size` limitation.\
If you want to just ignore the files that exceed a certain size, but process all others, then please use [🤖/file/filter](/docs/robots/file-filter.md).

* ### `allow_steps_override`

`boolean`\
Set this to false to disallow Overruling Templates at Runtime. If you set this to false then template\_id and steps will be mutually exclusive and you may only supply one of those parameters. Recommended when deploying Transloadit in untrusted environments. This makes sense to set as part of a Template, rather than on the Assembly itself when creating it.

* ### `notify_url`

`string | null`\
Transloadit can send a Pingback to your server when the Assembly is completed. We’ll send the Assembly status in a form url-encoded JSON string inside of a transloadit field in a multipart POST request to the URL supplied here.

* ### `fields`

`Record<string, any>`\
An object of string keyed values (name -> value) that can be used as Assembly Variables, just like additional form fields can. You can use anything that is JSON stringifyable as a value

* ### `quiet`

`boolean`\
Set this to true to reduce the response from an Assembly POST request to only the necessary fields. This prevents any potentially confidential information being leaked to the end user who is making the Assembly request. A successful Assembly will only include the ok and assembly\_id fields. An erroneous Assembly will only include the error, http\_code, message and assembly\_id fields. The full Assembly Status will then still be sent to the notify\_url if one was specified.

* ### `steps`

`Record<string, object & object>`\
Contains Assembly Instructions.

* ### `template_id`

`string`\
The ID of the Template that contains your Assembly Instructions. If you set `allow_steps_override` to `false` in your Template, then `steps` and `template_id` will be mutually exclusive — you may supply only one of these parameters.

## Response

Here’s an example response body:

![](/_next/static/media/copy.04p1cju9qekk_.svg?dpl=dpl_CoPVn8CkpFeWcaTxe6tAm4HNPmke)

```
{
  "ok": "ASSEMBLY_EXECUTING",
  "http_code": 200,
  "message": "The assembly is currently being executed.",
  "assembly_id": "0fce5b1063e611e88d8eb130f7921d8a",
  "parent_id": null,
  "account_id": "6c8b8d10d68b11e3a799b579dfce333a",
  "template_id": null,
  "instance": "morven.transloadit.com",
  "assembly_url": "http://api2.morven.transloadit.com/assemblies/0fce5b1063e611e88d8eb130f7921d8a",
  "assembly_ssl_url": "https://api2-morven.transloadit.com/assemblies/0fce5b1063e611e88d8eb130f7921d8a",
  "uppyserver_url": "https://api2-morven.transloadit.com/uppy-server/",
  "websocket_url": "https://api2-morven.transloadit.com/ws20243",
  "tus_url": "https://api2-morven.transloadit.com/resumable/files/",
  "bytes_received": 1687,
  "bytes_expected": 1687,
  "upload_duration": 0.049,
  "start_date": "2018/05/30 08:47:19 GMT",
  "warnings": [],
  "execution_start": "2018/05/30 08:47:19 GMT",
  "execution_duration": 0.001,
  "queue_duration": 0.04,
  "jobs_queue_duration": 0,
  "fields": {},
  "bytes_usage": 0,
  "template": null,
  "uploads": [
    // …
  ],
  "results": {
    // …
  }
}
```

For more information about the response, please refer to our documentation for the [Assembly Status response](/docs/api/assembly-status-response.md).