Move or rename a DAM asset

Moves or renames a DAM asset without changing its stored object.

Before calling this endpoint, obtain the IDs of existing assets in the same Workspace as the Auth Key used for the request.

For files stored with /transloadit/store, retrieve their Assembly Status and wait for ASSEMBLY_COMPLETED. In the returned results[stepName] arrays, retain each stored file’s asset_id, not its ordinary file id. Use these values for ASSET_ID or params.asset_ids in the examples below.

For a non-root destination, you must already know the existing folder’s ID in the same Workspace. A previously saved move or rename response can provide this ID: folder_id from a single-asset response or assets[].folder_id from a bulk-move response. These responses describe the folder after that operation; they are not a folder-discovery API.

There is currently no public endpoint for looking up a DAM folder ID by path. If you do not already have the destination folder ID, contact support before attempting a non-root move. To move to the root, use destination_folder_id: null.

Include at least one of filename or destination_folder_id inside params. A filename must be a name without a folder path.

To rename an asset in its current folder, send only filename inside params, as in the request example below.

To move the asset to the root instead, explicitly include destination_folder_id: null:

{ "destination_folder_id": null, "filename": "renamed.jpg" }

For another folder, replace null with its folder ID. Omission and null are different operations.

Asset path limits

The complete destination path (folders plus filename) must fit within 512 Unicode code points and 1024 UTF-8 bytes after normalization. A filename that fits on its own can still exceed these limits in a nested folder.

Request example

Set ASSET_ID 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.

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=dam: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

curl --fail-with-body -sS --request PATCH \
  --url "https://api2.transloadit.com/dam/assets/${ASSET_ID:?Set ASSET_ID}" \
  --header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
  --data-urlencode 'params={"filename":"renamed.jpg"}'

This endpoint accepts signed params or a bearer token. See Authentication for setup instructions.

Required scope for the Auth Key or bearer token: dam:write.

Signed requests require both a signature and a future params.auth.expires timestamp. Bearer tokens do not require either.

Content type: application/x-www-form-urlencoded

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.