API Docs
Topics
We offer ready-to-use SDKs for most major programming languages and platforms and generally recommend using those. However, if there is no suitable SDK for your situation, or perhaps you are building one, we explain all the details of our bare bones REST API on this page.
Resources
Transloadit provides a JSON REST API that can be used for:
- Creating, checking up on, or deleting Assemblies
- Checking up on, or replaying Assembly Notifications
- Creating, updating, checking up on, or deleting Templates
- Checking up on Billing
Here’s a complete overview:
Method | URL | Description | Signature Auth | Documentation |
---|---|---|---|---|
Assemblies | ||||
POST |
/assemblies
|
Create a New Assembly | optional | Documentation |
GET |
/assemblies/{ASSEMBLY_ID}
|
Retrieve an Assembly Status | not supported | Documentation |
DELETE |
/assemblies/{ASSEMBLY_ID}
|
Cancel a running Assembly | not supported | Documentation |
POST |
/assemblies/{ASSEMBLY_ID}/replay
|
Replay an Assembly | required | Documentation |
GET |
/assemblies
|
Retrieve List of Assemblies | required | Documentation |
Assembly Notifications | ||||
POST |
/assembly_notifications/{ASSEMBLY_ID}/replay
|
Replay Assembly Notification | required | Documentation |
GET |
/assembly_notifications
|
Retrieve List of Assembly Notifications | required | Documentation |
Billing | ||||
GET |
/bill/{DATE}
|
Retrieve a month's bill | required | Documentation |
Queue | ||||
JOB_SLOTS |
/queues
|
Retrieve currently used priority job sslots | required | Documentation |
Templates | ||||
POST |
/templates
|
Create a New Template | required | Documentation |
GET |
/templates/{TEMPLATE_ID}
|
Retrieve a Template | required | Documentation |
PUT |
/templates/{TEMPLATE_ID}
|
Edit a Template | required | Documentation |
DELETE |
/templates/{TEMPLATE_ID}
|
Delete a Template | required | Documentation |
GET |
/templates
|
Retrieve List of Templates | required | Documentation |
Response Codes
The following lists the response codes returned by Transloadit, which you can use to handle errors.
An Assembly is running if ok
is either ASSEMBLY_UPLOADING
or ASSEMBLY_EXECUTING
. All other states mean the Assembly has completed. If it completed in error, the error
property will be set. More details on ok
and error
codes can be found below.
OK Codes
OK codes are always returned via ok
key, like this: { ok: "{OK_CODE}" }
.
-
ASSEMBLY_CANCELED
The Assembly was canceled. -
ASSEMBLY_COMPLETED
The Assembly was completed successfully. -
ASSEMBLY_EXECUTING
The Assembly is currently being executed. -
ASSEMBLY_REPLAYING
The Assembly is being replayed. -
ASSEMBLY_UPLOADING
The Assembly is still in the process of being uploaded. -
REQUEST_ABORTED
The upload connection was closed or timed out before receiving all data.
Error Codes
Error codes are always returned via the error
key, like this: { error: "{ERROR_CODE}" }
.
-
ADMIN_PERMISSIONS_REQUIRED
You require admin permissions to do this. -
ASSEMBLIES_UPDATED
The Assemblies have been updated. -
ASSEMBLY_ACCOUNT_MISMATCH
You are not allowed to access this Assembly because it is not yours. -
ASSEMBLY_CANNOT_BE_REPLAYED
The Assembly cannot be replayed. -
ASSEMBLY_CRASHED
The process managing this Assembly crashed and could not be restored. -
ASSEMBLY_DISALLOWED_ROBOTS_USED
Your Assembly uses one or more disallowed Robots. -
ASSEMBLY_EMPTY_STEPS
Your Assembly {steps: …} parameter is empty. -
ASSEMBLY_EXPIRED
The Assembly expired. -
ASSEMBLY_FILE_ACCEPTED
The Assembly accepted the added file. -
ASSEMBLY_FILE_NOT_RESERVED
A place for this file must be reserved before adding it. -
ASSEMBLY_FILE_RESERVED
The Assembly reserved a space for this file. -
ASSEMBLY_INFINITE
Your Assembly appears to be infinite, at least one input file went through the same step twice. -
ASSEMBLY_INVALID_NOTIFY_URL
The Assembly had a malformed notify_url. They must be strings. -
ASSEMBLY_INVALID_NUM_EXPECTED_UPLOAD_FILES_PARAM
Your 'num_expected_upload_files' parameter value is invalid. It must be a number greater than or equal zero. -
ASSEMBLY_INVALID_STEPS
Your Assembly {steps: …} is a non-object value. -
ASSEMBLY_LIST_ERROR
Bad parameters -
ASSEMBLY_MEMORY_LIMIT_EXCEEDED
The Assembly memory limit of 8MB was exceeded. Please try to import less files and/or upload a zip file with less files. -
ASSEMBLY_NOTIFICATION_LIST_ERROR
Bad parameters -
ASSEMBLY_NOTIFICATION_NOT_REPLAYED
The Assembly notification could not be replayed. -
ASSEMBLY_NOT_CAPABLE
This Assembly is not capable of handling the requested endpoint. -
ASSEMBLY_NOT_FINISHED
The Assembly is not finished yet and thus cannot be replayed yet. -
ASSEMBLY_NOT_FOUND
The Assembly you requested crashed or does not exist. -
ASSEMBLY_NOT_REPLAYED
The Assembly could not be replayed -
ASSEMBLY_NO_CHARGEABLE_STEP
An Assembly must have at least one transcoding or export Step. -
ASSEMBLY_NO_NOTIFY_URL
The Assembly had not configured any notify_url. -
ASSEMBLY_NO_STEPS
Your Assembly does not include a {steps: …} parameter. -
ASSEMBLY_PROGRESS_UPDATED
The Assembly's upload progress has been updated. -
ASSEMBLY_SATURATED
This Assembly has already received all expected file uploads. -
ASSEMBLY_STATUS_NOT_FOUND
The status for the Assembly you requested could not be found. -
ASSEMBLY_STATUS_PARSE_ERROR
There was a problem parsing the status json of the Assembly. -
ASSEMBLY_STEP_INVALID
One of your {steps: …} parameters is a non-object value. -
ASSEMBLY_STEP_INVALID_ROBOT
One of your step parameters includes an non-string {robot: …} value. -
ASSEMBLY_STEP_INVALID_USE
One of your step parameters either includes a non-array {use: …} value or the members of the "use" array are not strings or objects. If they are objects, they must contain a "name" property. -
ASSEMBLY_STEP_NO_ROBOT
One of your step parameters did not include a {robot: …} key. -
ASSEMBLY_STEP_UNKNOWN_ROBOT
One of your step parameters is referencing an unknown {robot: …}. -
ASSEMBLY_STEP_UNKNOWN_USE
One of your step parameters references an unknown {use: …} value. -
AUTH_EXPIRED
The given auth expires parameter is in the past. -
BAD_PRICING
Something is wrong with the pricing record attached to your app, please contact support. -
BILL_LIMIT_EXCEEDED
The bill limit that was configured for this app is exceeded this month. -
CDN_REQUIRED
We recommend URL Transform is only used in combination with a CDN to cache results. Otherwise each hit is transcoded which may ramp up bills fast for popular pages. That's why you should (have your CDN) set the query parameter or header key: 'cdn' with the value: 'required'. -
COMPANION_BASIC_AUTH_UNSET
Unable to validate Basic Auth credentials -
COMPANION_CREDENTIALS_REQUEST_INVALID
Companion credentials request contains invalid data -
FILE_DOWNLOAD_ERROR
Transloadit was unable to download an external file. -
FILE_META_DATA_ERROR
There was a problem extracting meta data information from your file. -
GET_ACCCOUNT_DB_ERROR
Could not get app, there was a database error. -
GET_ACCOUNT_UNKNOWN_AUTH_KEY
Could not get app, this is an unknown Auth Key. -
IMPORT_FILE_ERROR
Transloadit was unable to import a file. -
INCOMPLETE_PRICING
Something is wrong with the pricing record attached to your app, please contact support. -
INTERNAL_COMMAND_ERROR
One of our commands reported an error. -
INVALID_ASSEMBLY_STATUS
This is an invalid Assembly status. -
INVALID_AUTH_EXPIRES_PARAMETER
Invalid auth expires parameter provided - we could not parse it. -
INVALID_AUTH_KEY_PARAMETER
Invalid Auth Key parameter provided - the value is not a string. -
INVALID_AUTH_MAX_SIZE_PARAMETER
Invalid auth referer parameter provided, could not parse it. -
INVALID_AUTH_REFERER_PARAMETER
Invalid auth referer parameter given, could not parse it. -
INVALID_FILE_META_DATA
We could not parse the meta data for the file #file#. -
INVALID_FORM_DATA
The form contained bad data, which cannot be parsed. -
INVALID_PARAMS_FIELD
Bad params field provided, it contains invalid json. -
INVALID_SIGNATURE
The given signature does not match ours. -
INVALID_STEP_NAME
You must not name a step ":original" that is not using the /upload/handle Robot. This will lead to bad job spawning like duped jobs or infinite Assemblies. -
INVALID_TEMPLATE_FIELD
Bad Template field provided, it contains invalid json. -
INVALID_UPLOAD_HANDLE_STEP_NAME
When using the /upload/handle robot, its step name must be ":original". -
MAX_SIZE_EXCEEDED
The uploaded file exceeded the file size limit. -
NO_AUTH_EXPIRES_PARAMETER
No auth expires parameter was provided. -
NO_AUTH_KEY_PARAMETER
No Auth Key parameter provided. -
NO_AUTH_PARAMETER
No auth parameter provided. -
NO_COUNTRY
Your app has no country record attached to it, please contact support or update your app information. -
NO_OBJECT_AUTH_PARAMETER
Bad auth parameter provided, it is not an object. -
NO_OBJECT_PARAMS_FIELD
Bad params field provided, it is not an object. -
NO_PARAMS_FIELD
No params field provided. -
NO_PRICING
Your app has no pricing record attached to it, please contact support. -
NO_RESULT_STEP_FOUND
Invalid or no result Step defined, which is mandatory for URL Transform Assemblies. -
NO_SIGNATURE_FIELD
No signature field was provided. -
NO_TEMPLATE_ID
This app demands that a Template ID is provided. None was provided, though. -
PLAN_LIMIT_EXCEEDED
You have exceeded the usage limit of your Transloadit plan. Please upgrade your plan to make this error message go away, or get in touch with support. -
POSSIBLY_MALICIOUS_FILE_FOUND
One of your files is possibly malicious and cannot be processed. -
QUEUES_LIST_ERROR
There was an error fetching the queue stats -
RATE_LIMIT_REACHED
Request limit reached -
REFERER_MISMATCH
This request comes from a location that is not allowed. -
REQUEST_PREMATURE_CLOSED
The original request was closed prematurely. -
SERVER_401
Authorization required -
SERVER_403
Forbidden -
SERVER_404
Unknown method / url -
SERVER_500
Unexpected error -
TEMPLATE_CREATED
Your Template was successfully created. -
TEMPLATE_CREDENTIALS_CREATED
Your Template Credentials were successfully created. -
TEMPLATE_CREDENTIALS_DELETED
Your Template Credentials were successfully deleted. -
TEMPLATE_CREDENTIALS_FOUND
Your Template Credentials were successfully found. -
TEMPLATE_CREDENTIALS_INJECTION_ERROR
Your Template Credentials could not be injected. -
TEMPLATE_CREDENTIALS_NOT_CREATED
Your Template Credentials could not be created. -
TEMPLATE_CREDENTIALS_NOT_DELETED
Your Template Credentials could not be deleted. -
TEMPLATE_CREDENTIALS_NOT_FOUND
Your Template Credentials could not be found. -
TEMPLATE_CREDENTIALS_NOT_UPDATED
Your Template Credentials could not be updated. -
TEMPLATE_CREDENTIALS_TYPES_FOUND
The Template Credentials types were successfully found. -
TEMPLATE_CREDENTIALS_TYPES_NOT_FOUND
The Template Credentials types could not be found. -
TEMPLATE_CREDENTIALS_UPDATED
Your Template Credentials were successfully updated. -
TEMPLATE_DB_ERROR
The Template for this request could not be fetched due to a db error. -
TEMPLATE_DELETED
Your Template was successfully deleted. -
TEMPLATE_DENIES_STEPS_OVERRIDE
This Template had theallow_steps_override
option set totrue
, so clients are not allowed to temper with its steps. -
TEMPLATE_FOUND
Your Template was successfully found. -
TEMPLATE_INVALID_JSON
Your Template contained invalid JSON. -
TEMPLATE_LIST_ERROR
Bad parameters -
TEMPLATE_NOT_FOUND
There was no Template found for the given template_id and app. -
TEMPLATE_UPDATED
Your Template was successfully updated. -
TEMPLATE_VALIDATION_ERROR
Your Template didn't pass validation. -
TMP_FILE_DOWNLOAD_ERROR
Transloadit was unable to download a file from our temporary location. -
VERIFIED_EMAIL_REQUIRED
You need to first verify your email address before you can do this. -
WORKER_JOB_ERROR
Transloadit was unable to process this Assembly.
Metadata
Many files contain interesting information about their contents. This is called "metadata". Transloadit automatically extracts this metadata for all uploaded, imported, and processed files.
At the very minimum, each file will have the information such as:
{
"id": "ae52b7f8c1b3426e8c29ea0a9daf8306",
"name": "straw-apple.jpg",
"basename": "straw-apple",
"ext": "jpg",
"size": 92230,
"mime": "image/jpeg",
"type": "image",
"field": "test_file",
"url": "http://tmp.maynard.transloadit.com/upload/1324a798a99fce7f5f8289a95a74f02b.jpg",
"original_id": "4af24fb2595f44809f3adc2f77bc9bfa",
"meta": { ... }
}
The information we can extract depends on the media file, its type, but also who produced it.
If it was an iPhone, there's probably latitude
in there for geo-positioning. More
common keys include height
, and duration
.
To see what information we can extract from files that you will throw at us, you could try one of our demos and inspect our response after uploading a file there.
-
id
A random and unique ID used internally by Transloadit to track the file. -
name
The name of the file. Transloadit will change the extension used for this field if the file undergoes processing into a different format. -
basename
The name of the file without the extension. -
ext
The extension of the file. -
size
The size of the file, in bytes. -
mime
The determined MIME type for this file. -
type
An abstract type describing the file, which can currently be"image"
,"video"
,"audio"
, ornull
. -
field
The name of the form field used to submit this file. -
url
The URL at which this file can be accessed. This is either a URL in your S3 bucket, or a temporary URL on our servers. Since temporary URLs expire after a few hours, you should make sure to move your files elsewhere unless you are using a storage robot. -
original_id
The unique ID of the original upload file from which this file was generated. This is useful to determine which file of a multi-file upload was used to generate a given file, after several Steps of processing. -
meta
An object containing additional metadata extracted from the file, as shown below.
Image Metadata
Although it depends on the file at hand,
files whose mime type is image
can typically contain data such as the following inside the meta
property:
-
width
The width of the input image, in pixels. -
height
The height of the input image, in pixels. -
aspect_ratio
The aspect ratio of the image, which is its width divided by its height. Will be 0 if for some reason the image height is 0. -
date_recorded
The date and time at which this image was taken, in the formatYYYY/MM/DD HH:MM:SS TZ
, such as"2010/06/30 22:16:06 GMT"
. -
date_file_created
The creation time for the file system. -
date_file_modified
The modification time for the file system. -
title
The title of this image, such as"Tree"
. -
keywords
An array of keywords for this image, such as["tree", "nature"]
. -
description
A description of this image, such as"This tree is very old."
. -
location
The location at which this image was taken, which is usually the street, such as"Zingster Str. 32"
. -
creator
The creator that took the image. -
author
The author that took the image. Some cameras populate this field as opposed tocreator
. -
copyright
The copyright metadata field. -
copyright_notice
The copyright notice metadata field. -
city
The city in which this image was taken, such as"Berlin"
. -
state
The state in which this image was taken, such as"Berlin"
. -
country
The country in which this image was taken, such as"Germany"
. -
country_code
The country code of the country in which this image was taken, such as"de"
. -
aperture
The aperture setting for this image, such as5.7
. -
exposure_compensation
The exposure compensation for this image, such as"+4/3"
. -
exposure_mode
The exposure mode for this image, such as"Auto"
. -
exposure_time
The exposure time for this image, such as"1/30"
. -
flash
The flash settings for this image, such as"Off, Did not fire"
. -
focal_length
The focal length for this image, such as"55.0 mm"
. -
f_number
The f-number for this image, such as5.6
. -
iso
The ISO value for this image, such as800
. -
light_value
The light value for this image, such as6.9
. -
metering_mode
The metering mode for this image, such as"Multi-segment"
. -
shutter_speed
The shutter speed for this image, such as"1/32"
. -
white_balance
The white balance setting for this image, such as"Manual"
. -
device_name
The device name of the camera, such as"iPhone 3GS"
. -
device_vendor
The camera manufacturer, such as"Apple"
. -
device_software
The version of the device software for the camera, such as"3.1.2"
. -
latitude
The latitude at which this image was taken, such as52.5374
. -
longitude
The longitude at which this image was taken, such as13.4034
. -
thumbnail_index
The index of the current thumbnail starting at 0. This key is only present for results of the /video/thumbs Robot. -
thumbnail_offset
The offset for the current thumbnail, in seconds. This key is only present for results of the /video/thumbs Robot. -
frame_count
The number of frames in an animated GIF file. This is1
by default for all other image types. -
colorspace
The colorspace of the image. This could be"sRGB"
or"Gray"
for instance. In Transloadit's first ImageMagick stack version, there's a bug which would make the colors used in an image determine itscolorspace
, and a grayscale colored image would report"Gray"
, even if saved as"RGB"
. -
has_clipping_path
Is1
if the image contains a clipping path,0
otherwise. -
average_color
Requested by many, and added January 2015, the average color used in the image. Not to be confused with dominant color, that counts a single most occurring pixel color and has limited use cases. The average color is calculated by first scaling the input image to 1 pixel. -
has_transparency
Returnstrue
for images that have transparent areas. This key is only returned if you setoutput_meta.has_transparency
totrue
. -
dominant_colors
Returns an array of the 20 most used colors for images. This key is only returned if you setoutput_meta.dominant_colors
totrue
.
Video Metadata
Although it depends on the file at hand,
files whose mime type is video
can typically contain data such as the following inside the meta
property:
-
width
The width of the video, in pixels. If the video was meant to be displayed with a different display ratio than the pixel ratio, this indicates the width at which the video is to be displayed. -
height
The height of the video, in pixels. -
framerate
The frame rate of the video, such as29.5
. -
video_bitrate
The video bit rate of the video, such as500000
. -
video_codec
The video codec of the video, such as"ffh264"
. -
audio_bitrate
The audio bit rate of the video, such as128000
. -
audio_samplerate
The audio sample rate of the video, such as44100
. -
audio_channels
The number of audio channels in the video, such as2
. -
audio_codec
The audio codec of the video, such as"faad"
. -
seekable
Whether the format of the video supports seeking, such astrue
. -
date_recorded
For details, see the description for image metadata. -
date_file_created
For details, see the description for image metadata. -
date_file_modified
For details, see the description for image metadata. -
device_name
For details, see the description for image metadata. -
device_vendor
For details, see the description for image metadata. -
device_software
For details, see the description for image metadata. -
latitude
For details, see the description for image metadata. -
longitude
For details, see the description for image metadata.
Audio Metadata
Although it depends on the file at hand,
files whose mime type is audio
can typically contain data such as the following inside the meta
property:
-
duration
The length of the audio file in seconds. -
audio_bitrate
Bits per second (for all channels combined). -
audio_samplerate
The audio sample rate in herz, such as44100
, for a CD. -
audio_channels
Number of channels. Typically 2, for stereo. -
audio_codec
The Audio codec used. Here's a list of all audio codecs that Transloadit supports. -
artist
Many applications that produce audio write additional information into the audio file such asartist
,year
,album
,genre
.
API Security
There are many security measures deployed at Transloadit. For the purpose of communicating with the REST API, it is important to note that:
- All of our endpoints listed below are accessible via HTTPS with A+ grading on SSL Labs to ensure encryption in transit.
- With Signature Authentication, you can ensure no one else is sending requests on your behalf, or tampering with them. You can make Templates require valid Signatures.
- We hold on to the least amount of data possible. Read more on this in our Privacy Policy.
- You can make Templates reject unrecognized HTTP Referer values (although some browsers do not send these, in which case you are better off rolling out Signature Authentication).
- You can set a bill limit, after which Transloadit stops processing anything. We're happy to scale up with your usage, but bill limits are a good way to prevent "infinite loop"-type bugs from making you (and/or us) go bankrupt
Rate Limiting
We enforce rate limits to guarantee that no customers are adversely affected by the usage of any given customer. Buggy integration code can result in too many requests being sent in a short period of time, leading to excessively high bills or increased queue times.
We have two Assembly limits in place:
- Customers can create up to 250 Assemblies per minute
- Customers can have 250 Assemblies running at the same time
In our experience, this satisfies even top-tier usage, but enterprise accounts are free to contact us if they require higher limits.
The limits are in place mostly to shield customers from other customers' "infinite loop"-type of programming bugs.
Customers that hit a rate limit will receive a RATE_LIMIT_REACHED
error. The JSON payload for this error contains an info.retryIn
property that indicates the number of seconds remaining until another Assembly can be created. If you use one of our official SDKs, proper back-offs and retries based on this are already included.
The following is an example of what the JSON payload may look like:
{
"error": "RATE_LIMIT_REACHED",
"message": "Request limit reached",
"info": {
"retryIn": 41
}
}
Queues
Encoding is hard work and it's quicker to submit an encoding request than it is to execute that request. Any customer can flood our systems with requests for hundreds of terabytes worth of video imports in just a second, and these could all be valid requests.
To deal with peaks, we have spare capacity on standby. But given finite budgets, the headroom is finite too. That's why we'll parallely scale up machines to handle peaks beyond that available "headroom", which we can do within a minute. In that time, Jobs could be queueing up. To make sure Jobs that require a real-time feel are impacted the least, we have made a separation between high (live) priority, and low (batch) priority traffic.
- If you use direct file uploads, your Assembly's Encoding Jobs are put into our Live Queue scheduled for immediate processing. You can think of the Live Queue as our fast lane, while the Batch Queue is for trucks only. This way, we can accept both huge library conversions as well as real-time avatar resizes without the former blocking the latter.
- If you use our import Robots with more than one file import per Robot, your Assemblies are considered to be a "batch import" and are placed into our Batch Queue right away. If there are many "trucks" in traffic, this can drastically impact execution times.
- If you set
queue: 'batch'
in your Steps, you can downgrade to a lower priority queue yourself (but not upgrade). You would do this when you want your large backlog of media library transcoding to not steal capacity away from your high priority Jobs - or just to be a good citizen :) - If you send too many Live Jobs, they can trickle down into the Batch Queue as to not affect other customers' performance.
Encoding Jobs take up a varying number of Job Slots. A /video/encode Job takes up 60 Slots, whereas an /image/resize Job only takes up 10 Slots.
Let's say your plan comes with a Job Slot Limit of 120 (this is always per region). That means in each region you could have 12 concurrent image resizes or 2 video encodings before jobs would be trickling down into the Batch Queue.
The Batch Queue isn't necessarily slower than the Live Queue, but whenever there are more Jobs than resources available, the Live Queue is prioritized.
As indicated, the tipping point for trickling down is controlled by the Job Slot Limit. It actually defines two values:
- How many Live Queue Job Slots a customer account can claim at any given time, for all requesting IPs.
- How many Live Queue Job Slots a single IP can claim at any given time.
The single IP value is often lower and helps to protect your end users from other end users that have extraordinary uses.
To avoid being impacted by degraded performance due to this, you can do two things:
1. Get a higher Job Slot Limit by upgrading your plan. Higher plans have higher throughput, and you can also contact us if you're interested in custom values.
2. Set waitForEncoding
to false
(available in, e.g., the Uppy integration). This makes sure media processing is handled in an asynchronous way, so two-minute queue times won't block the end-user experience. As soon as the files are uploaded to us, the user is on their way. We ping your notify_url
when the files are ready, and you notify your user. You can find more on this in the documentation for Assembly Notifications. This is the recommended way of integrating Transloadit and you should use it whenever you allow uploading files from a client. It is not only the best experience for your users, but it also offers the most reliability: it allows you to enable Assembly Replays in case there was a problem, because you already have a way to notify your user/systems in an indirect way.
You can see our current queue times for both Live Queues and Batch Queues on our Status Page, and programmatically access them via our Queues API Endpoint (the values are in seconds).
Assemblies
Create a New Assembly
https://api2.transloadit.com/assemblies
An Assembly can process and export files. Assembly Instructions determine how we should process them. Instructions can be passed in directly (inside a steps
parameter), or be saved in a Template (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.
POST Fields
-
Passing
signature
is optional. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
You can also supply other POST fields (that are not named params
or signature
) here. They can be used as variables to make your Assembly Instructions dynamic.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
steps
object ⋅ default:{}
Contains Assembly Instructions. Example:
Note: By default you may use the"encoded": { "use": ":original", "robot": "/video/encode", "preset": "iphone-high" }, "thumbed": { "use": "encoded", "robot": "/video/thumbs", "count": 8 }
steps
parameter to overrule Template Steps at runtime. If you setallow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. See Overruling Templates at Runtime. -
template_id
string ⋅ default:""
The ID of the Template that contains your Assembly Instructions. If you setallow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. -
notify_url
string ⋅ default:""
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 atransloadit
field in a multipart POST request to the URL supplied here. -
fields
object ⋅ default:{}
An object of string to string pairs (name -> value) that can be used as Assembly Variables, just like additional form fields can. For example, to dynamically have us resize images based on an end-user provided width, you could use${fields.user_width}
in your Assembly Instructions, and either post an<input name="user_width" value="800" />
or supply thisfields
param with the following object:{ "user_width": 800 }
-
allow_steps_override
boolean ⋅ default: trueSet this tofalse
to disallow Overruling Templates at Runtime. If you set this tofalse
thentemplate_id
andsteps
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.
Response
Here’s an example response body:
For more information about the response, please refer to our documentation for the Assembly Status response.
Retrieve an Assembly Status
https://api2.transloadit.com/assemblies/{ASSEMBLY_ID}
In the response after creating an Assembly you will find a field: assembly_ssl_url
. You can poll this URL every few seconds (or what is a sensible interval for your use case) to get the latest Assembly Status.
The assembly_ssl_url
will contain the machine name responsible for managing the Assembly. It knows in realtime how many bytes have been uploaded. An example URL would be: https://api2-jane.transloadit.com/assemblies/{ASSEMBLY_ID}
.
Due to scaling algorithms we cycle though machines quickly, so you can also fall back to removing the machine name and using: https://api2.transloadit.com/assemblies/{ASSEMBLY_ID}
. This will also get you the Assembly Status, but it might be outdated a little, due to eventual consistency reasons.
This request can be issued by anyone who knows the assembly_ssl_url
. Hence, make sure to not share your assembly_ssl_url
s or assembly_id
s with anybody. More on this in our FAQ under: Are the UUIDs that Transloadit uses for files and Assembly IDs secure?
GET Query Components
No request query components needed.
Response
Here’s an example response body:
For more information about the response, please refer to our documentation for the Assembly Status response.
Cancel a running Assembly
https://api2.transloadit.com/assemblies/{ASSEMBLY_ID}
Cancels an Assembly (and upload if that is still in progress). The assembly_ssl_url
field contains the unique URL returned when the Assembly was created.
This request can be issued by anyone who knows the assembly_ssl_url
. Hence, make sure to not share your assembly_ssl_url
s or assembly_id
s with anybody. More on this in our FAQ under: Are the UUIDs that Transloadit uses for files and Assembly IDs secure?
DELETE Fields
No request fields needed.
Response
Here’s an example response body:
Either returns the latest Assembly Status (in JSON) or a JSON error ASSEMBLY_NOT_FOUND
. Please refer to our documentation for the Assembly Status response.
Replay an Assembly
https://api2.transloadit.com/assemblies/{ASSEMBLY_ID}/replay
If an Assembly crashed, and if we can recover the input files, Transloadit can retry its execution.
You can specify a new notify_url
parameter in params
to avoid replaying the URL already specified for the Assembly.
Specify the steps
parameter to override the Steps of the original Assembly being replayed.
The newly created Assembly will have a parent_assembly_status
in its Status, pointing to the URL of the original crashed Assembly that it is a Replay of.
POST Fields
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
steps
object ⋅ default:{}
Contains Assembly Instructions. Example:
Note: By default you may use the"encoded": { "use": ":original", "robot": "/video/encode", "preset": "iphone-high" }, "thumbed": { "use": "encoded", "robot": "/video/thumbs", "count": 8 }
steps
parameter to overrule Template Steps at runtime. If you setallow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. See Overruling Templates at Runtime. -
template_id
string ⋅ default:""
The ID of the Template that contains your Assembly Instructions. If you setallow_steps_override
tofalse
thensteps
andtemplate_id
will be mutually exclusive and you may only supply one of these parameters. -
notify_url
string ⋅ default:""
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 atransloadit
field in a multipart POST request to the URL supplied here. -
fields
object ⋅ default:{}
An object of string to string pairs (name -> value) that can be used as Assembly Variables, just like additional form fields can. For example, to dynamically have us resize images based on an end-user provided width, you could use${fields.user_width}
in your Assembly Instructions, and either post an<input name="user_width" value="800" />
or supply thisfields
param with the following object:{ "user_width": 800 }
-
reparse_template
integer ⋅ default:0
Specify1
to reparse the Template used in your Assembly (useful if the Template changed in the meantime). Alternatively,0
replays the identical Steps used in the Assembly.
Response
Here’s an example response body:
We either return the success code ASSEMBLY_REPLAYING
or an error response code detailing what went wrong.
Retrieve List of Assemblies
https://api2.transloadit.com/assemblies?signature={SIGNATURE}¶ms={PARAMS}
Retrieves a list of Assemblies for your account. They are sorted by creation date descending.
GET Query Components
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should be first JSON encoded and then URL Encoded with the keys as shown in the table below.
Supported keys inside the params
query component
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
page
integer ⋅ default:1
Specifies the current page, within the current pagination -
pagesize
integer(1
-5000
) ⋅ default:50
Specifies how many Assemblies to be received per API request, which is useful for pagination. -
assembly_id
string ⋅ default:"all"
Specifies the types of Assemblies to be retrieved. This can be one ofall
,uploading
,executing
,canceled
,completed
,failed
orrequest_aborted
. -
type
string ⋅ default:"all"
Specifies the types of Assemblies to be retrieved. This can be one ofall
,uploading
,executing
,canceled
,completed
,failed
orrequest_aborted
. -
fromdate
string requiredSpecifies the minimum Assembly UTC creation date/time. Only Assemblies after this time will be retrieved. Use the formatY-m-d H:i:s
. -
todate
string ⋅ default:NOW()
Specifies the maximum Assembly UTC creation date/time. Only Assemblies before this time will be retrieved. Use the formatY-m-d H:i:s
. -
keywords
array of strings ⋅ default:[]
Specifies keywords to be matched in the Assembly Status. The Assembly fields checked include theid
,redirect_url
,fields
, andnotify_url
, as well as error messages and files used.
Response
We either return the error code ASSEMBLY_LIST_ERROR
or a JSON list of found Assemblies.
Assembly Status Response
Transloadit uses a single response format for creating and querying Assemblies, appending responses to upload forms, and sending Notifications.
The following is a full example of a Transloadit response. Since files are processed in parallel, the ordering for results
does not necessarily follow the same order as uploads
. There could also be multiple results for a single upload. To match results with uploads, you can use the original_id
field, which is present in both items.
Example Response
Explanation of fields
-
ok
Indicates a successful status. If the Assembly encountered an error, theerror
key below is used instead of this key. -
error
Indicates an error status. This key is only present if the Assembly failed. -
A human-readable message explaining the state of this Assembly. This is not always present.
-
assembly_id
The unique ID of this Assembly. You can store this in a database when an Assembly is created, and use it to match incoming Notifications. -
assembly_url
The unique URL used to query the current status of this Assembly. -
assembly_ssl_url
The unique URL used to query the current status of this Assembly, but ready to be used over SSL/HTTPS. All API requests that are sent to theassembly_url
can also be sent to theassembly_ssl_url
. -
companion_url
The URL to the Companion server that this Assembly may communicate with. -
websocket_url
The URL to a Websocket (uses Socket.IO) server from which you can get realtime status updates of this Assembly. -
tus_url
The URL to the tus server used by this Assembly. -
bytes_received
The number of bytes that have been uploaded to this Assembly so far. This is primarily used by clients to display upload progress. -
bytes_expected
The number of bytes that this Assembly expects to be uploaded. -
bytes_usage
The total number of bytes that this Assembly processed that count towards your usage bill. The sum ofbytes_usage
of all of your Assemblies equal your total monthly usage. -
client_agent
The user agent (browser) used by the uploader. -
client_ip
The IP address of the uploader. -
client_referer
The referrer URL of the uploader. -
start_date
The date and time at which upload started for this Assembly. -
upload_duration
The time taken by the uploader to upload files, in seconds. -
execution_duration
The time taken by Transloadit to execute this Assembly, in seconds. -
fields
A key/value map of any additional fields present in your form, for integrations can not use<form>
encapsulation (like Uppy). -
uploads
An array of files uploaded for this Assembly. For more information, see the metadata docs. -
results
The result files that Transloadit has produced so far. Each key of this object is the name of the Step that produced a particular file. As storage robots do not produce files, their Step names are not included here. In case of anerror
may contain partial results.
Assembly Notifications
Replay Assembly Notification
https://api2.transloadit.com/assembly_notifications/{ASSEMBLY_ID}/replay
Replays an Assembly Notification, sending the POST request containing the Assembly result JSON again to the notify_url
that was specified when the Assembly was created.
POST Fields
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
notify_url
string ⋅ default:Supplying a newnotify_url
in the params field is optional. You can use this to send the Notification to a new URL. If this parameter is not provided, the Notification is sent to thenotify_url
that was specified when the Assembly was created. -
wait
boolean ⋅ default: trueIf it is provided with the valuefalse
, then the API request will return immediately even though the Notification is still in progress. This can be useful if your server takes some time to respond, but you do not want to the replay API request to hang.
Response
Here’s an example response body:
Either returns with the success code ASSEMBLY_NOTIFICATION_REPLAYED
or with the proper error code detailing what went wrong.
If waitForEncoding
was set to false
, the success code will be ASSEMBLY_NOTIFICATION_REPLAYING
.
Retrieve List of Assembly Notifications
https://api2.transloadit.com/assembly_notifications?signature={SIGNATURE}¶ms={PARAMS}
GET Query Components
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should be first JSON encoded and then URL Encoded with the keys as shown in the table below.
Supported keys inside the params
query component
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
page
integer ⋅ default:1
Specifies the current page, within the current pagination -
pagesize
integer(1
-5000
) ⋅ default:50
Specifies how many Assemblies to be received per API request, which is useful for pagination. -
type
string ⋅ default:"all"
Specifies the type of Notifications to be retrieved. This can be eithersuccessful
,failed
orall
(default), which means both successful and failed Notifications are retrieved. -
assembly_id
string ⋅ default:""
Only finds Notifications for the Assembly identified by the given ID.
Response
Either returns with the error code ASSEMBLY_NOTIFICATION_LIST_ERROR
or with a JSON list of found Notifications.
Billing
Retrieve a month's bill
https://api2.transloadit.com/bill/{DATE}?signature={SIGNATURE}
Retrieves the billing data for the given DATE
.
The query component DATE
is in YYYY-MM
format. So for example, to retrieve your bill for March 2019 you would use 2019-03
.
GET Query Components
-
Passing
signature
is required. For more information please check Signature Authentication.
Response
Here’s an example response body:
On success this request returns a JSON response with the success code BILL_FOUND
and the corresponding bill data. The invoice_id
in the response will be null
for the bill of the current month.
On error it contains a JSON response including an error
field that contains an error status code and a reason
field that contains details on what went wrong.
Queue
Retrieve currently used priority job sslots
https://api2.transloadit.com/queues
Retrieves the sum of priority job slots that are currently in use in the count
field of the response.
It also shows in which Assemblies, their step names and the corresponding Job Ids slots are used. Please include Assembly Ids and Job Ids in your support tickets so we can inspect the logs for them for you.
JOB_SLOTS Fields
-
Passing
signature
is required. For more information please check Signature Authentication.
Response
Here’s an example response body:
On success this request returns a JSON response with the success code PRIORITY_JOB_SLOTS_FOUND
and the corresponding job slot data.
On error it contains a JSON response including an error
field that contains an error status code and a reason
field that contains details on what went wrong.
Templates
Create a New Template
https://api2.transloadit.com/templates
POST Fields
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
name
string requiredName of this Template. Must be between 5-40 symbols (inclusive), lowercase, can only contain dashes and latin letters. -
template
string requiredAll the Assembly Instructions as a JSON encoded string. -
require_signature_auth
integer ⋅ default:0
Use1
to deny requests that do not include a signature. With Signature Authentication you can ensure no one else is sending requests on your behalf.
Response
Here’s an example response body:
On success this request returns a JSON response with the success code TEMPLATE_CREATED
, the Template ID, name and content.
On error it contains a JSON response including an error
field that contains an error status code and a reason
field that contains details on what went wrong.
Retrieve a Template
https://api2.transloadit.com/templates/{TEMPLATE_ID}?signature={SIGNATURE}¶ms={PARAMS}
GET Query Components
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should be first JSON encoded and then URL Encoded with the keys as shown in the table below.
Supported keys inside the params
query component
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot.
Response
Here’s an example response body:
On success this request returns a JSON response with the success code TEMPLATE_FOUND
and the Template ID.
On error it contains a JSON response including an error
field that contains an error status code and a reason
field that contains details on what went wrong.
Edit a Template
https://api2.transloadit.com/templates/{TEMPLATE_ID}
Updates the Template represented by TEMPLATE_ID
with the new Template name and Template JSON.
PUT Fields
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
name
string ⋅ default: Existing nameName of this Template. Must be between 5-40 symbols (inclusive), lowercase, can only contain dashes and latin letters. -
template
string ⋅ default: Existing templateAll the new Assembly Instructions as a JSON encoded string. -
require_signature_auth
integer ⋅ default: Existing require_signature_authUse1
to deny requests that do not include a signature. With Signature Authentication you can ensure no one else is sending requests on your behalf.
Response
Here’s an example response body:
Upon error, the error
key will contain the corresponding error status code.
Delete a Template
https://api2.transloadit.com/templates/{TEMPLATE_ID}
Deletes a Template. Assemblies that make use of this Template will no longer work.
DELETE Fields
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should contain a JSON encoded object with the keys as shown in the table below.
Supported keys inside the params
field
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot.
Response
Here’s an example response body:
Upon error, the error
key will contain the corresponding error status code.
Retrieve List of Templates
https://api2.transloadit.com/templates?signature={SIGNATURE}¶ms={PARAMS}
GET Query Components
-
Passing
signature
is required. For more information please check Signature Authentication. -
Passing
params
is required. It should be first JSON encoded and then URL Encoded with the keys as shown in the table below.
Supported keys inside the params
query component
-
auth
object requiredContains at least your Transloadit Auth Key in thekey
property. If you enable Signature Authentication, you'll also set an expiry date for the request in theexpires
property like so:
The{ "key": "23c96d084c744219a2ce156772ec3211", "expires": "2021/01/01 16:53:14+00:00" }
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. Themax_size
property can be used to set a maximum size that an upload can have in bytes, such as1048576
(1 MB). Specify this to prevent users from uploading excessively large files. When using this key, make sure that it is specified as a hiddenmax_size
form field, since settingmax_size
in a Template will have no effect. 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, even if it contains files that do not exceed themax_size
limitation. If you want to just ignore the files that exceed a certain size, but process all others, then please use our /file/filter Robot. -
page
integer ⋅ default:1
Specifies the current page, within the current pagination -
pagesize
integer(1
-5000
) ⋅ default:50
Specifies how many Templates to be received per API request, which is useful for pagination. -
sort
stringThe field to sort by. Default value is"created"
. Valid values are["id", "name", "created", "modified"]
. -
order
stringThe sort direction. Can be"desc"
for descending (default) or"asc"
for ascending. -
fromdate
string requiredSpecifies the minimum Assembly UTC creation date/time. Only Templates after this time will be retrieved. Use the formatY-m-d H:i:s
. -
todate
string ⋅ default:NOW()
Specifies the maximum Assembly UTC creation date/time. Only Templates before this time will be retrieved. Use the formatY-m-d H:i:s
. -
keywords
array of strings ⋅ default:[]
Specifies keywords to be matched in the Assembly Status. The Assembly fields checked include theid
,redirect_url
,fields
, andnotify_url
, as well as error messages and files used.
Response
Either returns with the error code TEMPLATE_LIST_ERROR
or with a JSON list of found Templates.