Edit a Template
Updates an existing Template by its ID or name.
https://api2.transloadit.com/Updates the Template represented by TEMPLATE_ID_OR_NAME. Omitted top-level settings normally remain
unchanged, so the request example below renames the Template without changing its Instructions.
Supplying template replaces the stored Instructions in full; it does not merge or patch
individual Steps. Include every Step and Instruction you want to keep in that object.
Cron scheduling is an invited paid preview. Each participating Workspace may enable one
Template, with at most 10,000 admitted ticks per UTC day. Supply cron_region, a six-field
cron_schedule_with_seconds, and cron_auth_key_id before setting cron_enabled to true.
The selected Auth Key must belong to this Workspace and permit Assembly creation.
The caller must also have Assembly creation permission when enabling or editing an active schedule.
Disabling scheduling does not require Assembly creation permission. If scheduling becomes
unavailable or the Workspace loses preview access, an ordinary Template edit automatically
disables scheduling while preserving its region, schedule, Auth Key ID, and existing run.
Disabling a Template or pausing its Workspace, region, or the scheduler prevents future
admissions. A tick already admitted durably may still finish.
Schedules run in UTC and must keep every pair of consecutive ticks at least 10 seconds
apart. Instructions must use self-contained HTTP or S3 imports and cannot depend on uploaded
files through :original or /upload/handle. Scheduled Assemblies import at most 1,000 input
files and honor a lower authored max_number_of_files limit. Execution changes take effect
at the next future tick. Missed ticks are skipped. cron_max_concurrent_runs defaults to 1;
raise it up to 10 to allow simultaneous scheduled runs. Pending starts and unresolved runs
count toward the limit across Template edits and disable/re-enable cycles. At the limit,
ticks are skipped with outcome and reason overlap; they are not queued for later.
Lowering the limit does not cancel existing runs. Manual Assemblies do not count toward it,
and ordinary Workspace limits still apply. This setting does not deduplicate imported files.
A consumed start without an Assembly checkpoint retains its slot until its configurable
timeout, which defaults to 10 minutes. It is then marked lost with reason
start_checkpoint_missing, allowing later ticks to proceed. That tick is never retried.
An Assembly that remains crashed without a recovery checkpoint for the same timeout becomes
lost with reason recovery_checkpoint_missing, also allowing future ticks to proceed.
Aborted or failed Assemblies retain overlap until their jobs finish. If a final checkpoint
never arrives, they expire after the Workspace’s maximum Assembly lifetime plus checkpoint
grace, then use the same bounded loss timeout without restarting the aborted or failed work.
A late Assembly checkpoint corrects the retained outcome with reason start_checkpoint_late.
Lost runs permanently release their slots. A late Assembly may therefore temporarily exceed
the configured limit, including the default of 1; this is not a strict execution mutex.
Request example
Set TEMPLATE_ID_OR_NAME to your resource value without percent-encoding it.
Run this request in a server-side shell with curl and a suitable bearer token in TRANSLOADIT_TOKEN. If you need a token, expand the setup below.
Need a bearer token?
In a trusted server-side shell with curl and jq, set TRANSLOADIT_KEY and TRANSLOADIT_SECRET to your Auth Key and Auth Secret. Keep both credentials and the resulting token secret; never run this setup in browser code.
First, create a token with this endpoint’s required scopes. Your Auth Key must already grant those scopes.
if ! TOKEN_RESPONSE="$(curl --fail-with-body -sS \
--request POST \
--url 'https://api2.transloadit.com/token' \
--user "${TRANSLOADIT_KEY:?Set TRANSLOADIT_KEY}:${TRANSLOADIT_SECRET:?Set TRANSLOADIT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'aud=api2' \
--data-urlencode 'scope=templates:write')"; then
printf '%s\n' "$TOKEN_RESPONSE" >&2
exit 1
fi
TRANSLOADIT_TOKEN="$(printf '%s' "$TOKEN_RESPONSE" |
jq -er '.access_token | strings | select(length > 0)')" || exit 1
Keep this shell open and run the request below. Reuse the token while it remains valid.
curl --fail-with-body -sS --request PUT \
--url "https://api2.transloadit.com/templates/${TEMPLATE_ID_OR_NAME:?Set TEMPLATE_ID_OR_NAME}" \
--header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
--data-urlencode 'params={"name":"resized-images"}'
Authentication
This endpoint accepts signed params or a bearer token. See Authentication for setup instructions.
Required scope for the Auth Key or bearer token: templates:write.
Signed requests require both a signature and a future params.auth.expires timestamp. Bearer tokens do not require either.
Path parameters
templateIdOrName(path segment), required. pattern:^[a-z0-9-]+$, minimum length: 1
Form fields
Content type: application/x-www-form-urlencoded
params(JSON string), required. A JSON-encoded object whose supported keys are listed below.signature(string). Required for signed requests. Omit this field when using a bearer token.
Supported keys inside the params field
Authentication fields in this list apply to signed requests. With a bearer token, you can omit params.auth and the separate signature field. Compare the authentication-specific request parameters below.
Complete JSON Schema
params: Only the fields listed for this object are accepted.
| Field | Type and description | ||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params. | "1day" | "30days" | "7days" | "90days" | "NoSave"Controls how long the Assembly Status is retained for Assemblies created from this Template. | ||||||||||||||||||||||||||||||||||||
params.required for signed requests; optional with a bearer token | Contains the Transloadit API key and signature-authentication metadata for a Template request.
| ||||||||||||||||||||||||||||||||||||
params.required | stringISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. | ||||||||||||||||||||||||||||||||||||
params.required | stringTransloadit API key used to authenticate requests | ||||||||||||||||||||||||||||||||||||
params. | string | nullID of an active, unexpired Auth Key belonging to this Workspace, with permission to create Assemblies. Required when enabling the invited paid Cron Template preview. The key must permit signing and cannot be an internal key. Validation pattern (regular expression)^[a-f0-9]{32}$ | ||||||||||||||||||||||||||||||||||||
params. | booleanEnables or disables the invited paid Cron Template preview. Enabling or editing an active schedule requires the caller to have Assembly creation permission. Omission keeps the current setting while scheduling remains available; an ordinary edit automatically disables scheduling if preview access is withdrawn. Each invited paid Workspace may enable one Cron Template. Instructions must be self-contained, using HTTP or S3 imports without | ||||||||||||||||||||||||||||||||||||
params. | integer (minimum: 1, maximum: 10)Maximum simultaneous scheduled runs of this Template. Defaults to 1 on creation; omission on update preserves the saved limit. Ticks at the limit are skipped, not queued. Pending starts and unresolved runs count until completion or the checkpoint-loss timeout. Lost runs release their slot permanently, so a late Assembly may temporarily exceed this limit. Does not deduplicate imported files or limit manual Assemblies. Ordinary Workspace limits still apply. | ||||||||||||||||||||||||||||||||||||
params. | "ap-southeast-1" | "eu-west-1" | "us-east-1" | nullRegional API used for scheduled Assemblies. Required when enabling the invited paid Cron Template preview. | ||||||||||||||||||||||||||||||||||||
params. | string | null (minimum length: 1, maximum length: 255)Six-field numeric cron expression, evaluated in UTC: second, minute, hour, day of month, month, and weekday. Supports wildcards, comma-separated values, ranges, and steps. Scheduled ticks must be at least 10 seconds apart. Cron Template scheduling is an invited paid preview. | ||||||||||||||||||||||||||||||||||||
params. | string (minimum length: 3, maximum length: 200)Name of this Template. Use 3–200 lowercase Latin letters, numbers, or dashes. The name Validation pattern (regular expression)^(?:[a-su-z0-9-][a-z0-9-]{2,199}|t[a-ln-z0-9-][a-z0-9-]{1,198}|tm[a-oq-z0-9-][a-z0-9-]{0,197}|tmp[a-z0-9-]{1,197})$ | ||||||||||||||||||||||||||||||||||||
params. | string | integerUnique, random value included in signed request params to make each signature unique and prevent accidental signature reuse. | ||||||||||||||||||||||||||||||||||||
params. | 0 | 1Use | ||||||||||||||||||||||||||||||||||||
params. | object | stringAssembly Instructions stored in this Template. Prefer the structured JSON object; a JSON-encoded string remains accepted for compatibility. Any of the following schemas may apply: objectStructured Assembly Instructions stored in this Template.
stringstringJSON-encoded Assembly Instructions retained for client compatibility. Validation pattern (regular expression)^[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*\{(?:[^\x00]|\x00)*\}[\x09-\x0D\x20\xA0\u1680\u2000\u2001\u2002\u2003\u2004\u2005\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff]*$ | ||||||||||||||||||||||||||||||||||||
params. | "1day" | "NoSave"Controls how long transcoding results are retained for Assemblies created from this Template. |
Request parameters by authentication method
With signed params
Include your Auth Key as params.auth.key. When signing the request, include a future params.auth.expires timestamp and send the signature in the separate signature field. The field definitions below use paths inside params.
Complete JSON Schema
params: Only the fields listed for this object are accepted.
Uses the field definitions above: params.assembly_status_expiry, params.auth, params.cron_auth_key_id, params.cron_enabled, params.cron_max_concurrent_runs, params.cron_region, params.cron_schedule_with_seconds, params.name, params.nonce, params.require_signature_auth, params.template, params.transcoding_result_expiry
With a bearer token
Send the bearer token in the Authorization header. You can omit params.auth and the separate signature field. Other required parameters still apply. The field definitions below use paths inside params.
Complete JSON Schema
params: Only the fields listed for this object are accepted.
Uses the field definitions above: params.assembly_status_expiry, params.cron_auth_key_id, params.cron_enabled, params.cron_max_concurrent_runs, params.cron_region, params.cron_schedule_with_seconds, params.name, params.nonce, params.require_signature_auth, params.template, params.transcoding_result_expiry
| Field | Type and description |
|---|---|
params. | Contains the Transloadit API key and signature-authentication metadata for a Template request.
|
params. | stringISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. |
params. | stringTransloadit API key used to authenticate requests |
Response
Here’s an example response body:
{
"assembly_status_expiry": null,
"content": {
"steps": {
"resize": {
"robot": "/image/resize",
"use": ":original",
"width": 320
}
}
},
"id": "8fc3b9166c784afd824acf24269ebd11",
"message": "Your Template was successfully updated.",
"name": "resized-images",
"ok": "TEMPLATE_UPDATED",
"require_signature_auth": 0,
"transcoding_result_expiry": null
}2xx success
JSON response body. application/json text/plain; charset=utf-8
Response body schema
Complete JSON Schema
The response contains only the fields listed for this object.
| Field | Type and description |
|---|---|
assembly_status_expiryrequired | null | string |
contentrequired | object | Array<any value> | string | number | boolean | nullAny of the following schemas may apply: objectobjectAdditional property schemaany valueArray<any value>Array<any value>Array item schemaany valuestringnumberbooleannull |
cron_auth_key_id | string | nullValidation pattern (regular expression)^[a-f0-9]{32}$ |
cron_enabled | boolean |
cron_max_concurrent_runs | integer (minimum: 1, maximum: 10) |
cron_region | "ap-southeast-1" | "eu-west-1" | "us-east-1" | null |
cron_schedule_with_seconds | string | null (minimum length: 1, maximum length: 255) |
idrequired | stringAny of the following schemas may apply: Variant 1: string (maximum length: 32)stringValidation pattern (regular expression)^[\x00-\x7F]*$Variant 2: string (maximum length: 32)stringValidation pattern (regular expression)^builtin\/[a-z0-9-]+(?:@[0-9a-z.-]+)?$ |
messagerequired | string (minimum length: 1) |
namerequired | string (minimum length: 1, maximum length: 255) |
okrequired | string (always: "TEMPLATE_UPDATED") |
require_signature_authrequired | 0 | 1 |
transcoding_result_expiryrequired | null | string |
Error response
JSON response body. application/json text/plain; charset=utf-8
Response body schema
Complete JSON Schema
The response may contain additional fields.
| Field | Type and description |
|---|---|
assembly_id | string |
error | string (minimum length: 1) |
http_code | number | string
|
message | stringHuman-readable explanation of the error. Its wording can vary; use the |
reason | null | string | number | boolean | Array<any value> | objectAny of the following schemas may apply: nullstringnumberbooleanArray<any value>Array<any value>Array item schemaany valueobjectobjectAdditional property schemaany value |
HTTP 400
JSON response body. application/json text/plain; charset=utf-8
Response body schema
Complete JSON Schema
Named errors and the general error format
error: "TEMPLATE_VALIDATION_ERROR"
Your Template didn’t pass validation.
The response may contain additional fields.