Transloadit

List Storage assets

Lists bounded pages of Workspace assets with stable identities and current version metadata.

GEThttps://api2.transloadit.com/dam/assets

Returns metadata for current live assets in the authenticated Workspace, without downloading their bytes.

Pass next_cursor back as cursor with the same prefix to read the next page. Stop when next_cursor is null. Pages are bounded and do not form a snapshot: concurrent moves, writes, or deletion can change later pages.

The returned asset and version IDs can be saved and used with /transloadit/import. Use a trailing slash in the prefix to select a directory boundary, such as photos/ rather than photos.

Request example

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

Keep this shell open and run the request below. Reuse the token while it remains valid.

curl --fail-with-body -sS --request GET --get \
  --url "https://api2.transloadit.com/dam/assets" \
  --header "Authorization: Bearer ${TRANSLOADIT_TOKEN:?Set TRANSLOADIT_TOKEN}" \
  --data-urlencode 'params={"prefix":"photos/","limit":100}'

Authentication

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

Required scopes for the Auth Key or bearer token: dam:read, dam:write.

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

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

Open JSON in a new tab

params: Only the fields listed for this object are accepted.

FieldType and description
params.auth

required for signed requests; optional with a bearer token

object

Contains the Transloadit API key and signature-authentication metadata for a Storage metadata 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.auth.nonce
string | integer

Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse.

params.cursor
string (minimum length: 1, maximum length: 512)

Opaque continuation value from next_cursor in the previous response. Keep the same prefix while paging. Omit for the first page.

params.limit
integer (default: 100, minimum: 1, maximum: 500)

Maximum number of assets per page. Defaults to 100 and accepts up to 500; follow next_cursor until null.

params.prefix
string (default: "", maximum length: 512)

Only list current asset paths starting with this case-sensitive prefix. The empty default includes the whole Workspace; include a trailing slash to select a directory boundary.

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

Open JSON in a new tab

params: Only the fields listed for this object are accepted.

Uses the field definitions above: params.auth, params.cursor, params.limit, params.prefix

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

Open JSON in a new tab

params: Only the fields listed for this object are accepted.

Uses the field definitions above: params.cursor, params.limit, params.prefix

FieldType and description
params.auth
object

Contains the Transloadit API key and signature-authentication metadata for a Storage metadata 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

params.auth.nonce
string | integer

Unique, random value included in signed request params to make each signature unique and prevent accidental signature reuse.

Response

Here’s an example response body:

{
  "assets": [
    {
      "asset_id": "AAAAAAAAAAAAAAAAAAAAAA",
      "height": 600,
      "mime": "image/jpeg",
      "path": "renamed.jpg",
      "size": 12345,
      "version_id": "AAAAAAAAAAAAAAAAAAAAAQ",
      "width": 800,
      "workspace": "example-workspace"
    }
  ],
  "message": "The Storage assets were successfully listed.",
  "next_cursor": null,
  "ok": "DAM_ASSETS_LISTED",
  "workspace": "example-workspace"
}

2xx success

JSON response body. application/json text/plain; charset=utf-8

Response body schema
Complete JSON Schema

Open JSON in a new tab

The response contains only the fields listed for this object.

FieldType and description
assets

required

Array<object>
Array item schema
object

assets[]: The response may contain additional fields.

FieldType and description
assets[].asset_id

required

string

Stable asset ID. It survives native moves and renames; use it without a version to select the current bytes.

Validation pattern (regular expression)^[A-Za-z0-9_-]{21}[AQgw]$
assets[].height
integer (exclusive minimum: 0, maximum: 9007199254740991)

Display height in pixels, after applying EXIF orientation, when known.

assets[].md5hash
string

Lowercase MD5 checksum of the stored bytes, when available.

Validation pattern (regular expression)^[a-f0-9]{32}$
assets[].mime

required

null | string

MIME type of the stored bytes, or null when unknown.

assets[].path

required

string (minimum length: 1)

Current mutable location relative to the Workspace. A rename makes the previous path stale; overwriting can change the bytes at this path.

assets[].sha256
string

Lowercase SHA-256 checksum of the stored bytes, when available.

Validation pattern (regular expression)^[a-f0-9]{64}$
assets[].size

required

integer (minimum: 0, maximum: 9007199254740991)

Size of the stored file in bytes.

assets[].version_id

required

string

Exact immutable version of this asset. Pair with asset_id to select retained bytes; a missing version never falls back to the current version.

Validation pattern (regular expression)^[A-Za-z0-9_-]{21}[AQgw]$
assets[].width
integer (exclusive minimum: 0, maximum: 9007199254740991)

Display width in pixels, after applying EXIF orientation, when known.

assets[].workspace

required

string (minimum length: 1)

Workspace slug that owns this asset. Authenticate for the same Workspace when reading or managing it.

message

required

string (minimum length: 1)
next_cursor

required

null | string
ok

required

string (always: "DAM_ASSETS_LISTED")
workspace

required

string (minimum length: 1)

Workspace slug that owns this asset. Authenticate for the same Workspace when reading or managing it.

Error response

JSON response body. application/json text/plain; charset=utf-8

Response body schema
Complete JSON Schema

Open JSON in a new tab

At least one of these properties is required: error, message, reason

The response may contain additional fields.

FieldType and description
assembly_id
string
error
string (minimum length: 1)
http_code
number | string
  • number
  • string
    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]*[+-]?0*(?:0(?:[^0-9]|$)|(?:[1-9][0-9]{0,307}|1(?:(?:[0-6][0-9]{7}|7[0-8][0-9]{6}|79[0-6][0-9]{5}|797[0-5][0-9]{4}|7976[0-8][0-9]{3}|79769[0-2][0-9]{2}|7976930[0-9]{1}|7976931[0-2])[0-9]{300}|79769313(?:(?:[0-3][0-9]{7}|4[0-7][0-9]{6}|48[0-5][0-9]{5}|486[0-1][0-9]{4}|4862[0-2][0-9]{3}|486230[0-9]{2}|486231[0-4][0-9]{1}|4862315[0-7])[0-9]{292}|48623158(?:(?:0[0-6][0-9]{6}|07[0-8][0-9]{5}|079[0-2][0-9]{4}|0793[0-6][0-9]{3}|07937[0-1][0-9]{2}|079372[0-7][0-9]{1}|0793728[0-8])[0-9]{284}|07937289(?:(?:[0-6][0-9]{7}|70[0-9]{6}|71[0-3][0-9]{5}|7140[0-4][0-9]{3}|71405[0-2][0-9]{2}|7140530[0-2])[0-9]{276}|71405303(?:(?:[0-3][0-9]{7}|40[0-9]{6}|41[0-4][0-9]{5}|4150[0-6][0-9]{3}|41507[0-8][0-9]{2}|415079[0-8][0-9]{1}|4150799[0-2])[0-9]{268}|41507993(?:(?:[0-3][0-9]{7}|40[0-9]{6}|41[0-2][0-9]{5}|413[0-1][0-9]{4}|4132[0-6][0-9]{3}|413270[0-9]{2})[0-9]{260}|41327100(?:(?:[0-2][0-9]{7}|3[0-6][0-9]{6}|37[0-7][0-9]{5}|378[0-1][0-9]{4}|3782[0-5][0-9]{3}|37826[0-8][0-9]{2}|378269[0-2][0-9]{1}|3782693[0-5])[0-9]{252}|37826936(?:(?:0[0-9]{7}|1[0-6][0-9]{6}|17[0-2][0-9]{5}|173[0-6][0-9]{4}|1737[0-6][0-9]{3}|17377[0-7][0-9]{2}|173778[0-8][0-9]{1}|1737789[0-7])[0-9]{244}|17377898(?:(?:0[0-3][0-9]{6}|04[0-3][0-9]{5}|044[0-3][0-9]{4}|0444[0-8][0-9]{3}|04449[0-5][0-9]{2}|044496[0-7][0-9]{1}|0444968[0-1])[0-9]{236}|04449682(?:(?:[0-8][0-9]{7}|9[0-1][0-9]{6}|92[0-6][0-9]{5}|927[0-5][0-9]{4}|9276[0-3][0-9]{3}|92764[0-6][0-9]{2}|927647[0-4][0-9]{1})[0-9]{228}|92764750(?:(?:[0-8][0-9]{7}|9[0-3][0-9]{6}|94[0-5][0-9]{5}|946[0-5][0-9]{4}|9466[0-3][0-9]{3}|94664[0-8][0-9]{2}|94664900)[0-9]{220}|94664901(?:(?:[0-6][0-9]{7}|7[0-8][0-9]{6}|79[0-6][0-9]{5}|797[0-6][0-9]{4}|7977[0-4][0-9]{3}|79775[0-7][0-9]{2}|797758[0-6][0-9]{1}|7977587[0-1])[0-9]{212}|79775872(?:(?:0[0-6][0-9]{6}|070[0-8][0-9]{4}|0709[0-5][0-9]{3}|07096[0-2][0-9]{2}|070963[0-2][0-9]{1})[0-9]{204}|07096330(?:(?:[0-1][0-9]{7}|2[0-7][0-9]{6}|28[0-5][0-9]{5}|286[0-3][0-9]{4}|28640[0-9]{3}|28641[0-5][0-9]{2}|286416[0-5][0-9]{1}|2864166[0-8])[0-9]{196}|28641669(?:(?:[0-1][0-9]{7}|2[0-7][0-9]{6}|28[0-7][0-9]{5}|288[0-6][0-9]{4}|2887[0-8][0-9]{3}|288790[0-9]{2}|2887910[0-8])[0-9]{188}|28879109(?:(?:[0-3][0-9]{7}|4[0-5][0-9]{6}|46[0-4][0-9]{5}|465[0-4][0-9]{4}|4655[0-4][0-9]{3}|46555[0-4][0-9]{2}|465555[0-3][0-9]{1}|4655554[0-6])[0-9]{180}|46555547(?:(?:[0-7][0-9]{7}|8[0-4][0-9]{6}|850[0-9]{5}|851[0-8][0-9]{4}|8519[0-3][0-9]{3}|851940[0-3][0-9]{1})[0-9]{172}|85194040(?:(?:[0-1][0-9]{7}|2[0-5][0-9]{6}|26[0-2][0-9]{5}|2630[0-5][0-9]{3}|26306[0-4][0-9]{2}|263065[0-6][0-9]{1}|2630657[0-3])[0-9]{164}|26306574(?:(?:[0-7][0-9]{7}|8[0-7][0-9]{6}|88[0-5][0-9]{5}|886[0-6][0-9]{4}|88670[0-9]{3}|88671[0-4][0-9]{2}|8867150[0-4])[0-9]{156}|88671505(?:(?:[0-7][0-9]{7}|8[0-1][0-9]{6}|820[0-5][0-9]{4}|8206[0-7][0-9]{3}|820680[0-9]{2}|820681[0-8][0-9]{1})[0-9]{148}|82068190(?:(?:[0-7][0-9]{7}|8[0-8][0-9]{6}|890[0-1][0-9]{4}|8902000[0-6])[0-9]{140}|89020007(?:(?:0[0-7][0-9]{6}|08[0-2][0-9]{5}|083[0-7][0-9]{4}|0838[0-2][0-9]{3}|08383[0-5][0-9]{2}|083836[0-6][0-9]{1}|0838367[0-5])[0-9]{132}|08383676(?:(?:[0-1][0-9]{7}|2[0-6][0-9]{6}|27[0-2][0-9]{5}|273[0-7][0-9]{4}|2738[0-4][0-9]{3}|27385[0-3][0-9]{2}|273854[0-7][0-9]{1}|2738548[0-3])[0-9]{124}|27385484(?:(?:[0-4][0-9]{7}|5[0-7][0-9]{6}|580[0-9]{5}|581[0-6][0-9]{4}|5817[0-6][0-9]{3}|581770[0-9]{2}|5817710[0-9]{1}|5817711[0-4])[0-9]{116}|58177115(?:(?:[0-2][0-9]{7}|30[0-9]{6}|31[0-6][0-9]{5}|317[0-5][0-9]{4}|3176[0-3][0-9]{3}|31764[0-3][0-9]{2}|317644[0-6][0-9]{1}|3176447[0-4])[0-9]{108}|31764475(?:(?:[0-6][0-9]{7}|7[0-2][0-9]{6}|730[0-1][0-9]{4}|7302[0-6][0-9]{3}|7302700[0-5])[0-9]{100}|73027006(?:(?:[0-8][0-9]{7}|9[0-7][0-9]{6}|98[0-4][0-9]{5}|985[0-4][0-9]{4}|9855[0-4][0-9]{3}|98555[0-6][0-9]{2}|9855570[0-9]{1}|9855571[0-2])[0-9]{92}|98555713(?:(?:[0-5][0-9]{7}|6[0-5][0-9]{6}|66[0-8][0-9]{5}|669[0-4][0-9]{4}|6695[0-8][0-9]{3}|66959[0-5][0-9]{2}|669596[0-1][0-9]{1}|6695962[0-1])[0-9]{84}|66959622(?:(?:[0-7][0-9]{7}|8[0-3][0-9]{6}|84[0-1][0-9]{5}|842[0-8][0-9]{4}|84290[0-9]{3}|84291[0-3][0-9]{2}|842914[0-7][0-9]{1}|84291480)[0-9]{76}|84291481(?:(?:[0-8][0-9]{7}|9[0-7][0-9]{6}|98[0-5][0-9]{5}|9860[0-7][0-9]{3}|98608[0-2][0-9]{2}|986083[0-3][0-9]{1}|9860834[0-8])[0-9]{68}|98608349(?:(?:[0-2][0-9]{7}|3[0-5][0-9]{6}|36[0-3][0-9]{5}|364[0-6][0-9]{4}|3647[0-4][0-9]{3}|36475[0-1][0-9]{2}|364752[0-8][0-9]{1}|3647529[0-1])[0-9]{60}|36475292(?:(?:[0-6][0-9]{7}|70[0-9]{6}|71[0-8][0-9]{5}|7190[0-6][0-9]{3}|71907[0-3][0-9]{2}|7190740[0-9]{1}|7190741[0-5])[0-9]{52}|71907416(?:(?:[0-7][0-9]{7}|8[0-3][0-9]{6}|84[0-3][0-9]{5}|844[0-3][0-9]{4}|8444[0-2][0-9]{3}|84443[0-5][0-9]{2}|844436[0-4][0-9]{1}|8444365[0-4])[0-9]{44}|84443655(?:(?:0[0-9]{7}|10[0-6][0-9]{5}|1070[0-3][0-9]{3}|10704[0-2][0-9]{2}|107043[0-3][0-9]{1}|1070434[0-1])[0-9]{36}|10704342(?:(?:[0-6][0-9]{7}|70[0-9]{6}|710[0-9]{5}|711[0-4][0-9]{4}|7115[0-4][0-9]{3}|71155[0-8][0-9]{2}|711559[0-5][0-9]{1}|7115596[0-8])[0-9]{28}|71155969(?:(?:[0-8][0-9]{7}|9[0-4][0-9]{6}|950[0-7][0-9]{4}|95080[0-8][0-9]{2}|950809[0-2][0-9]{1})[0-9]{20}|95080930(?:(?:[0-3][0-9]{7}|4[0-1][0-9]{6}|42[0-7][0-9]{5}|428[0-7][0-9]{4}|428800[0-9]{2}|428801[0-6][0-9]{1}|4288017[0-6])[0-9]{12}|42880177(?:(?:[0-8][0-9]{7}|90[0-3][0-9]{5}|9040[0-9]{4}|9041[0-6][0-9]{3}|90417[0-3][0-9]{2}|904174[0-3][0-9]{1}|9041744[0-8])[0-9]{4}|90417449(?:(?:[0-6][0-9]{3}|7[0-6][0-9]{2}|77[0-8][0-9]{1}|7790)|7791))))))))))))))))))))))))))))))))))))))))(?:[^0-9]|$))
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<any value> | object

Any of the following schemas may apply:

null
null
string
string
number
number
boolean
boolean
Array<any value>
Array<any value>
Array item schema
any value
object
object
Additional property schema
any value