# Retrieve a Template Returns a Template by its ID or name. `GET` `https://api2.transloadit.com/templates/{templateIdOrName}` Set `TEMPLATE_ID_OR_NAME` to a Workspace Template’s ID or name. For a Builtin Template, keep the literal `/` and `@` separators in its identifier. Use one of these assignments before running the request example below: * `TEMPLATE_ID_OR_NAME='builtin/encode-hls-video@0.0.1'` selects that specific version. * `TEMPLATE_ID_OR_NAME='builtin/encode-hls-video@latest'` selects the latest version. * `TEMPLATE_ID_OR_NAME='builtin/encode-hls-video'` also selects the latest version. Do not encode these separators as `%2F` or `%40`. The canonical path constraint below applies to Workspace Templates; Builtin Templates use the additional slash-bearing path shown here. Discover their versioned IDs with `include_builtin` on [List Templates](/docs/api/templates-get.md). ## Request example Set `TEMPLATE_ID_OR_NAME` to your resource value without percent-encoding it. Canceled Workspaces cannot create new bearer tokens. This endpoint remains available with an existing active Auth Key: use the [signed read recipe](/docs/api/authentication.md#read-access-after-cancellation) instead of the token setup below. The key must grant this endpoint’s required scopes. Run this request in a server-side shell with `curl` and a suitable [bearer token](/docs/api/token-post.md) 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. ```bash 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:read')"; 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. ```bash curl --fail-with-body -sS --request GET --get \ --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={}' ``` ## Authentication This endpoint accepts signed `params` or a bearer token. See [Authentication](/docs/api/authentication.md) for setup instructions. Required scope for the Auth Key or bearer token: `templates:read`. 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 ## Query parameters * `params` (JSON string). 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 signed `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](/api-reference/schemas/templates-template-id-get/params-fields.json) `params`: Only the fields listed for this object are accepted. ### `params.auth` (required for signed requests; optional with a bearer token) [`object`](#params-fields-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Template request. `params.auth`: Only the fields listed for this object are accepted. #### `params.auth.expires` (required) `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. #### `params.auth.key` (required) `string` Transloadit API key used to authenticate requests ### `params.nonce` `string | integer` Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse. ## 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](/api-reference/schemas/templates-template-id-get/signed-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.auth`](#params-fields-auth), [`params.nonce`](#params-fields-nonce) ### 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](/api-reference/schemas/templates-template-id-get/bearer-params.json) `params`: Only the fields listed for this object are accepted. Uses the field definitions above: [`params.nonce`](#params-fields-nonce) #### `params.auth` [`object`](#bearer-params-auth-expires) Contains the Transloadit API key and signature-authentication metadata for a Template request. `params.auth`: Only the fields listed for this object are accepted. ##### `params.auth.expires` `string` ISO 8601 expiration timestamp in the future. Required when a request is signed or requires signature authentication; bearer-authenticated requests may omit it. ##### `params.auth.key` `string` Transloadit API key used to authenticate requests ## Response Here’s an example response body: ```jsonc { "assembly_status_expiry": null, "content": { "steps": { "resize": { "robot": "/image/resize", "use": ":original", "width": 320 } } }, "id": "8fc3b9166c784afd824acf24269ebd11", "message": "Your Template was successfully found.", "name": "resize-images", "ok": "TEMPLATE_FOUND", "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](/api-reference/schemas/templates-template-id-get/response-1-body.json) The response contains only the fields listed for this object. ##### `assembly_status_expiry` (required) `null | string` ##### `content` (required) `object | Array | string | number | boolean | null` **Any of the following schemas may apply:** * `object` * **Additional property schema** `any value` * `Array` * **Array item schema** `any value` * `string` * `number` * `boolean` * `null` ##### `id` (required) `string` **Any of the following schemas may apply:** * **Variant 1** `string` (maximum length: 32) Validation pattern (regular expression): `^[\x00-\x7F]*$` * **Variant 2** `string` (maximum length: 32) Validation pattern (regular expression): `^builtin\/[a-z0-9-]+(?:@[0-9a-z.-]+)?$` ##### `message` (required) `string` (minimum length: 1) ##### `name` (required) `string` (minimum length: 1, maximum length: 255) ##### `ok` (required) `string` (always: "TEMPLATE\_FOUND") ##### `require_signature_auth` (required) `0 | 1` ##### `transcoding_result_expiry` (required) `null | string` ### Error response JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/templates-template-id-get/response-2-body.json) At least one of these properties is required: error, message, reason The response may contain additional fields. ##### `assembly_id` `string` ##### `error` `string` (minimum length: 1) ##### `http_code` `number | string` * `number` * `string` [Validation pattern (regular expression)](/api-reference/schemas/templates-template-id-get/response-2-body.json) ##### `message` `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. ##### `reason` `null | string | number | boolean | Array | object` **Any of the following schemas may apply:** * `null` * `string` * `number` * `boolean` * `Array` * **Array item schema** `any value` * `object` * **Additional property schema** `any value` ### HTTP 400 JSON response body. `application/json` `text/plain; charset=utf-8` #### Response body schema [Complete JSON Schema](/api-reference/schemas/templates-template-id-get/response-3-body.json) **Named errors and the general error format** * **error: "SIGNATURE\_REUSE\_DETECTED"** The request was denied for security reasons. If you think this is in error, please get in touch with support. The response may contain additional fields. * **`error` (required)** `string` (always: "SIGNATURE\_REUSE\_DETECTED") * **`http_code`** `number` (always: 400) * **`message`** `string` Human-readable explanation of the error. Its wording can vary; use the `error` code when handling a specific failure. * **General error format** [See the general error response fields.](#response-2-body)