1. API Basics

1.1 Available APIs

Transloadit provides a simple JSON REST API that can be used for creating new Assemblies, checking the status of an Assembly, or deleting Assemblies.

There is also an API for managing Templates and Assembly Notifications.

Most API calls will require the following parameters:

Parameter Description

params

This is a JSON string containing the parameters for this request. This must include an auth.key parameter to identify your account. See Authentication.

signature

The Signature for the given params if you have enabled Signature Authentication (turned off by default).
For details about how to calculate this value, see Authentication.

1.2 API Security

There are two means built into the Transloadit API to access it securely:

  1. You can access all our HTTP URLs listed below in the Assembly API and Template API sections also via HTTPS.
  2. We offer signature authentication, which is complex enough to deserve its own section.

1.3 Rate Limiting

We enforce rate limits to guarantee that no customers are adversely affected by the usage of any given customer. Bulk imports and buggy integration code can result in too many requests being sent in a short period of time, leading to excessively large bills or increased queue times.

For now, we have two limits in place. The first one limits the number of Assemblies that a customer can create to 250 per minute. This is more than enough for reasonable usage. The second one imposes a limit of 250 concurrently executing Assemblies per customer.

Customers that hit a rate limit will receive a 413 RATE_LIMIT_REACHED error. The JSON payload for this error contains an info.retryIn parameter that indicates the number of seconds remaining until another Assembly can be created. We provide this information to make sure imports are throttled as little as necessary, to facilitate smooth customer integration.

The following is an example of what the JSON payload may look like:

{
  "error": "RATE_LIMIT_REACHED",
  "message": "Request limit reached",
  "info": {
    "retryIn": 41
  }
}

These limits help us ensure a great experience for all customers. If you have a lot of long running Assemblies, or you need to create a lot of Assemblies in a short amount of time, then please reach out to us at support@transloadit.com to get a limit increase.

1.4 Queues

If you use direct file uploads, your Assembly's encoding jobs are put into our live traffic queues for very fast processing. If you have many concurrent Assemblies, however, encoding jobs may be thrown into our batch processing queues to not affect other customers in a bad way.

The current limits are 40 job slots per client IP and 120 job slots per account id. Encoding jobs take up a varying number of job slots. A /video/encode job takes up 6 slots, whereas an /image/resize job only takes up 1 slot.

If you see degrading Assembly execution times when you issue load spikes, please contact us to have this limit raised for you.

If you use our import robots with more than one file import per robot, your Assemblies are considered to be a batch imports and are thrown into our batch processing queues, which will result in drastically worse execution times.

You can see our current queue times for both live and batch queues on our status page or programmatically on our queues API endpoint (the values there mean seconds).

2. Assembly API

2.1 Create a New Assembly

Request

POST http://api2.transloadit.com/assemblies

Required parameters

A POST field named params is mandatory. It contains parameters in an encoded JSON string. Possible parameters are: auth, steps, template_id and notify_url.

Optional parameters

Supplying a POST field named signature (containing a signature string) is optional here. For more information about signatures, please check Authentication.

You can also supply other POST fields (that are not named params or signature) here. They can be nice if you want to use them as variables to make your assembly instructions dynamic. A fields key can also be added to the params object to inject variables to the instructions that are independent of a form. Just supply them as an object of string to string pairs (name -> value).

Description

Creates a new Assembly. Multiple files can be included as part of a multipart/form-data request.

The response

Responds with the Status of the Assembly. Please refer to our documentation for the Assembly Status response.

2.2 Retrieve the Status of an Assembly

Request

GET {assembly_url}?signature={signature}

Requirement parameters

None

Optional parameters

Supplying the URL query field signature is optional. For more information about signatures, please check Authentication.

Description

Queries the status of an Assembly. assembly_url is the unique URL returned when the Assembly was created. This request can be issued by anyone who knows the assembly_url. Make sure to not share your assembly_url's or assembly_id's with anybody.

If you do not know your assembly_url you can also query https://api2.transloadit.com/assemblies/[[assembly_id]]. This will also get you the Assembly Status, even though it is not as up to date for Assemblies that are still uploading or executing.


The response

Please refer to our documentation for the Assembly Status response.

2.3 Cancel an Assembly

Request

DELETE {assembly_url}?signature={signature}

Required parameters

None

Optional parameters

Supplying the URL query field signature is optional. For more information about signatures, please check Authentication.

Description

Cancels an Assembly or upload that is still in progress. assembly_url is the unique URL returned when the, Assembly was created. This request can be issued by anyone who knows the assembly_url. Make sure to not share your assembly_url's or assembly_id's with anybody.

The response

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.

2.4 Replay Assembly

Request

POST http://api2.transloadit.com/assemblies/{assembly_id}/replay

Required parameters

Parameters encoded in a POST field named params JSON string, and a POST field named signature containing a signature string are mandatory. For more information about these two, please check Authentication. Possible params fields are: auth, steps, notify_url, reparse_template.

Optional parameters

None

Description

Replays an Assembly.

Specify a new notify_url parameter in params to avoid replaying the URL already specified for the Assembly.

Specify 1 for the reparse_template parameter in params to reparse the Template used in your Assembly (useful if the Template changed in the meantime). Otherwise, specify 0 (the default value) to replay the identical Steps used in the Assembly.

Specify the steps parameter in params to override the Steps of the original Assembly being replayed.

The response

Either returns with the success code ASSEMBLY_REPLAYING or with the proper error code detailing what went wrong.

2.5 Retrieve Assembly List

Request

GET http://api2.transloadit.com/assemblies?params={params}&signature={signature}

Required parameters

Parameters url-encoded in a JSON string in a URL query field named params, and a URL query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, type, fromdate, todate, keywords. Please see descriptions for the params fields below.

Optional parameters

None

Description

Retrieves a list of Assemblies for your account.

params can contain the following keys:

Parameter Description

page

Specifies the current page, within the current pagination. The default value is 1.

pagesize

Specifies how many Assemblies to be received per API request, which is useful for pagination. The maximum value is 5000. The default value is 50.

type

Specifies the types of Assemblies to be retrieved. This can be one of uploading, executing, canceled, completed, failed or request_aborted. The default value is all.

fromdate

Specifies the minimum Assembly creation date/time. Only Assemblies after this time will be retrieved. Use the format Y-m-d H:i:s.

todate

Specifies the maximum Assembly creation date/time. Only Assemblies before this time will be retrieved. Use the format Y-m-d H:i:s.

keywords

Specifies keywords to be matched in the Assembly JSON. The Assembly properties checked include the id, redirect_url, and notify_url properties, as well as error messages and files used.

The response

Either returns with the error code ASSEMBLY_LIST_ERROR or with a JSON list of found Assemblies.

2.6 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. To match a result with an upload, such as for multi-upload enabled forms, match the original_id field of the result with the original_id field of the uploads part of the response.

Example Response

Explanation of the Response

Key Description

ok

Indicates a successful status. If the Assembly encountered an error, the error key below is used instead of this key.

error

Indicates an error status. This key is only present if the Assembly failed.

message

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 the assembly_url can also be sent to the assembly_ssl_url.

bytes_received

The number of bytes that have been uploaded to this Assembly so far. This is primarily used by the jQuery SDK 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 of bytes_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 that do not use the jQuery SDK.

uploads

An array of files uploaded for this Assembly. For more information, see the metadata documentation.

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.

2.7 Response Codes

The following lists the response codes returned by Transloadit, which you can use to handle errors.

OK Codes

OK codes are always returned via ok key, like this: { ok: "${OK_CODE}" }.

Code Description

REQUEST_ABORTED

The upload connection was closed or timed out before receiving all data.

ASSEMBLY_UPLOADING

The Assembly is still in the process of being uploaded.

ASSEMBLY_EXECUTING

The Assembly is currently being executed.

ASSEMBLY_CANCELED

The Assembly was canceled.

ASSEMBLY_COMPLETED

The Assembly was completed successfully.

Error Codes

Error codes are always returned via the error key, like this: { error: error_code }.

Code Description

INVALID_FORM_DATA

The form data is invalid and cannot be parsed.

INVALID_FILE_META_DATA

The file is bad and its metadata cannot be parsed

NO_PARAMS_FIELD

No params field was given.

INVALID_PARAMS_FIELD

The params field or JSON is invalid.

NO_OBJECT_PARAMS_FIELD

The params field is not an object.

NO_AUTH_PARAMETER

No auth parameter was given.

NO_OBJECT_AUTH_PARAMETER

The auth parameter is not an object.

NO_AUTH_KEY_PARAMETER

No Auth Key parameter was given.

INVALID_AUTH_KEY_PARAMETER

The given Auth Key parameter is not a string.

NO_AUTH_EXPIRES_PARAMETER

No auth expires parameter was given.

INVALID_AUTH_MAX_SIZE_PARAMETER

The auth referer parameter could not be parsed.

MAX_SIZE_EXCEEDED

The uploaded file exceeded the maximum file size.

INVALID_AUTH_REFERER_PARAMETER

The auth referer parameter could not be parsed.

REFERER_MISMATCH

The request came from a disallowed location.

INVALID_AUTH_EXPIRES_PARAMETER

The auth expires parameter given could not be parsed.

AUTH_EXPIRED

The given auth expires parameter is in the past.

NO_SIGNATURE_FIELD

No signature field was given.

INVALID_SIGNATURE

The given signature does not match that calculated by Transloadit.

GET_ACCCOUNT_DB_ERROR

The account could not be found due to a database error.

GET_ACCOUNT_UNKNOWN_AUTH_KEY

The account could not be found due to an unknown Auth Key.

NO_COUNTRY

The account has no country record. Contact support, or update your account information.

NO_PRICING

The account has no pricing record. Contact support.

BAD_PRICING

The pricing record of the account is invalid. Contact support.

INCOMPLETE_PRICING

The pricing record of the account is incomplete. Contact support.

BILL_LIMIT_EXCEEDED

The billing limit set for the account has been exceeded this month.

CREDIT_EXCEEDED

The account credits have been exceeded. Add a credit card to the profile to resume service.

TEMPLATE_DB_ERROR

The Template for this request could not be fetched, due to a database error.

TEMPLATE_NOT_FOUND

No Template was found for the given template_id and account.

TEMPLATE_INVALID_JSON

The Template contains invalid JSON.

SERVER_404

The method or URL is not recognized.

FILE_META_DATA_ERROR

A problem occurred extracting metadata from the file.

ASSEMBLY_NOT_FOUND

The requested Assembly does not exist.

ASSEMBLY_NO_STEPS

The Assembly does not include a steps parameter.

ASSEMBLY_INVALID_STEPS

The Assembly steps parameter is not an object.

ASSEMBLY_EMPTY_STEPS

The Assembly steps parameter is empty.

ASSEMBLY_STEP_INVALID

One the Assembly steps parameters is not an object.

ASSEMBLY_STEP_INVALID_USE

One of the Step parameters contains a use value that is not an array.

ASSEMBLY_STEP_UNKNOWN_USE

One of the Step parameters is set to an unknown use value.

ASSEMBLY_INFINITE

The Assembly does not appear to end, as the same Step was performed twice for one or more input files.

ASSEMBLY_STEP_NO_ROBOT

One of the Step parameters did not include a robot key.

ASSEMBLY_STEP_INVALID_ROBOT

One of the Step parameters includes robot value that is not a string.

ASSEMBLY_STEP_UNKNOWN_ROBOT

One of the Step parameters is set to an unknown robot.

ASSEMBLY_CRASHED

The process managing this Assembly crashed, and could not be restored.

INTERNAL_TOOL_ERROR

One of our internal tools reported an error.

INTERNAL_COMMAND_ERROR

One of our commands reported an error.

VIDEO_ENCODE_INVALID_WATERMARK_POSITION

An invalid watermark_position array member was detected.

IMPORT_FILE_ERROR

A file was unable to be imported.

CLOUDFILES_STORE_ACCESS_DENIED

The given credentials could not be used to obtain an auth token from CloudFiles.

CLOUDFILES_STORE_ERROR

The given file could not be stored in the container.

FILE_FILTER_INVALID_OPERATOR

The accepts or declines array could not be parsed.

FILE_FILTER_DECLINED_FILE

One of the files was declined.

IMAGE_RESIZE_INVALID_WATERMARK_POSITION

An invalid watermark_position array member was detected.

WORKER_JOB_ERROR

This Assembly could not be processed.

QUEUE_DOWNLOAD_FILE_ERROR

This Assembly could not be processed.

2.8 File Meta Data

Many files contain interesting information about their contents, called "metadata". Transloadit automatically extracts this metadata for all uploaded or processed files.

At the very minimum, each file will have the information such as the following:

{
  "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 from 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 on of our demos and inspect our response after uploading a file there.

Key Description

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", or null.

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

Additional metadata extracted from the file, as shown below.

Image Meta Data

In addition to the information above, we try to extract the following information from files whose type is "image".

Key Description

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 format YYYY/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 to creator.

copyright

The copyright meta data field.

copyright_notice

The copyright notice meta data 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 as 5.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 as 5.6.

iso

The ISO value for this image, such as 800.

light_value

The light value for this image, such as 6.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 as 52.5374.

longitude

The longitude at which this image was taken, such as 13.4034.

thumbnail_index

The index of the current thumbnail starting at 0. This key is only present for results of the /video/thumbnails robot.

thumbnail_offset

The offset for the current thumbnail, in seconds. This key is only present for results of the /video/thumbnails.

frame_count

The number of frames in an animated GIF file. This is 1 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 its colorspace, and a grayscale colored image would report "Gray", even if saved as "RGB".

has_clipping_path

Is 1 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.

Video Metadata

Files whose type is "video" contain the following metadata:

Key Description

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 as 29.5.

video_bitrate

The video bit rate of the video, such as 500000.

video_codec

The video codec of the video, such as "ffh264".

audio_bitrate

The audio bit rate of the video, such as 128000.

audio_samplerate

The audio sample rate of the video, such as 44100.

audio_channels

The number of audio channels in the video, such as 2.

audio_codec

The audio codec of the video, such as "faad".

seekable

Whether the format of the video supports seeking, such as true.

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" typically contain the following metadata:

Key Description

duration

The duration of the audio file in seconds.

audio_bitrate

Bits per second (for all channels combined).

audio_samplerate

The audio sample rate in herz, such as 44100, 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 as artist, year, album, genre.

3. Notification API

3.1 Retrieve Assembly Notification List

Request

GET http://api2.transloadit.com/assembly_notifications?params={params}&signature={signature}

Required parameters

Parameters url-encoded in a JSON string in a URL query field named params, and a URL query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, type and assembly_id. Please see descriptions for the params fields below.

Optional parameters

None

Description

Retrieves a list of Assembly Notifications for your account.

params can contain the following keys:

Parameter Description

page

Specifies the current page, within the current pagination. The default value is 1.

pagesize

Specifies how many Notifications to be received per API request, which is useful for pagination. The maximum value is 5000. The default value is 50.

type

Specifies the type of Notifications to be retrieved. This can be either successful, failed or all (default), which means both successful and failed Notifications are retrieved.

assembly_id

Only finds Notifications for the Assembly identified by the given ID.

The response

Either returns with the error code ASSEMBLY_NOTIFICATION_LIST_ERROR or with a JSON list of found Notifications.

3.2 Replay Assembly Notification

Request

POST http://api2.transloadit.com/assembly_notifications/{assembly_id}/replay

The old request URL is now deprecated:
POST http://api2.transloadit.com/assemblies/{assembly_id}/replay_notification

Required parameters

Parameters encoded in a POST field named params JSON string, and a POST field named signature containing a signature string. For more information about these two, please check Authentication. Possible params fields are: auth, notify_url.

Optional parameters

Supplying a new notify_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 the notify_url that was specified when the Assembly was created.

You can also provide the parameter wait, which is true by default. If it is provided with the value false, 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.

Description

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.

The response

Either returns with the success code ASSEMBLY_NOTIFICATION_REPLAYED or with the proper error code detailing what went wrong.

If wait was set to false, the success code will be ASSEMBLY_NOTIFICATION_REPLAYING.

4. Template API

4.1 Create a New Template

Request

POST http://api2.transloadit.com/templates

Required parameters

A POST field named params is mandatory. It contains parameters in an encoded JSON string. The required parameters are: auth, name (the Template name) and template (the Template JSON string).

Supplying a POST field named signature (containing a signature string) is also mandatory. For more information about signatures, please check Authentication.

Optional parameters

None

Description

Creates a new Template.

The response

On success this request returns a JSON response with the success code TEMPLATE_CREATED, the Template ID, name and content.

Example:

{
  "ok": "TEMPLATE_CREATED",
  "template_id": "{the_template_id_string}",
  "template_content": "{the_template_content}",
  "template_name": "{the_template_name}"
}

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.

4.2 Retrieve a Template

Request

GET http://api2.transloadit.com/templates/{template_id}

Required parameters

Supplying a GET query field named params containing your Auth Key and auth expires value is mandatory. And so is providing a GET query field named signature (containing a signature string). For more information about signatures, please check Authentication.

Optional parameters

None

Description

Retrieves the Template JSON content for a given template_id.

The response

On success this request returns a JSON response with the success code TEMPLATE_FOUND and the Template ID.

Example:

{
  "ok": "TEMPLATE_FOUND",
  "template_id": "{the_template_id_string}",
  "template_content": "{the_template_content}",
  "template_name": "{the_template_name}"
}

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.

4.3 Edit a Template

Request

PUT http://api2.transloadit.com/templates/{template_id}

Required parameters

A POST field named params is mandatory. It contains parameters in an encoded JSON string. The required parameters are: auth, name (the new Template name) and template (the new Template JSON string).

Important If you do not wish to change the name of the Template, then please provide the old name of the Template as the new name.

Supplying a POST field named signature (containing a signature string) is also mandatory. For more information about signatures, please check Authentication.

Optional parameters

None

Description

Updates the Template represented by template_id with the new Template name and Template JSON.

The response

Returns a JSON string with { ok: "TEMPLATE_UPDATED" } upon success. Upon error, the error key will contain the corresponding error status code.

4.4 Delete a Template

Request

DELETE http://api2.transloadit.com/templates/{template_id}

Required parameters

A POST field named params is mandatory. It contains parameters in an encoded JSON string. The required parameters are: auth, which in turn contains key (your auth key) and expires. We have a separate documentation section on Authentication to explain this further.

Supplying a POST field named signature (containing a signature string) is also mandatory. For more information about signatures, please also check Authentication.

Optional parameters

None

Description

Deletes a Template. Assemblies that make use of this Template will no longer work.

The response

Returns a JSON string with { ok: "TEMPLATE_DELETED" } upon success. Upon error, the error key will contain the corresponding error status code.

4.5 Retrieve Template List

Request

GET http://api2.transloadit.com/templates?params={params}&signature={signature}

Required parameters

Parameters url-encoded in a JSON string in a URL query field named params, and a URL query field named signature containing a signature string. For more information about these two, please check Authentication.

Possible params fields are: auth, page, pagesize, sort, order, fromdate, todate, fields. Please see descriptions for the params fields below.

Optional parameters

None

Description

Retrieves a list of Assemblies for your account.

params can contain the following keys:

Parameter Description

page

Specifies the current page, within the current pagination. The default value is 1.

pagesize

Specifies how many Templates to be received per API request, which is useful for pagination. The maximum value is 5000.

sort

The field to sort by. Default value is "created". Valid values are ["id", "name", "created", "modified"].

order

The sort direction. Can be "desc" for descending (default) or "asc" for ascending.

fields

An array of fields to retrieve for each Template. The default values is ["id", "account_id", "name", "json", "created", "modified", "deleted"] which are all available fields. Valid values here are arrays that contain one or more of these field names.

fromdate

Specifies the minimum Template creation date/time. Only Templates after this time will be retrieved. Use the format Y-m-d H:i:s.

todate

Specifies the maximum Template creation date/time. Only Templates before this time will be retrieved. Use the format Y-m-d H:i:s.

The response

Either returns with the error code TEMPLATE_LIST_ERROR or with a JSON list of found Templates.

5. Billing API

5.1 Retrieve a month's bill

Request

GET http://api2.transloadit.com/bill/<month>

Required parameters

Supplying a GET query field named params containing your Auth Key and auth expires value is mandatory. And so is providing a GET query field named signature (containing a signature string). For more information about signatures, please check Authentication.

The month parameter in the URL must have the format Y-m, so for example 2014-03 for March in 2014.

Optional parameters

None

Description

Retrieves the billing data for the given month.

The response

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.

Example:

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.