Asset Query syntax

Any hyperlink to a collection of assets can accept query parameters that filter the returned assets, and specify the order.

Applicable endpoints

• /customers/{customer}/allImages
• /customers/{customer}/spaces/{space}/images

Once you have registered images with the platform you can query it for information on them. One immediate use of this is to monitor the progress of ongoing registrations. For example, if you registered a batch of 100,000 images it will take some time for the platform to process them, and you would like to be able to monitor progress and view any errors that were encountered. You can also query for usage statistics.

Permitted queries

Shortcut metadata fields

Only the 6 built-in string and number fields are supported.

?string1=my-value
?number1=99
?string1=my-value&number1=99

Query object

?q={"string1":"my-value"}
?q={"number1":99}
?q={"string1":"my-value","number1":99}
?q={"tags": ["my-tag"]}
?q={"tags": ["my-tag", "another-tag"]}
?q={"roles": ["https://api.dlcs.io/customers/2/roles/clickthrough"]}
?q={"id":"PHOTO.2.22.36.2.tif"}

Ordering

You can order by the value of a field of an asset:

?orderByDescending=width
?orderBy=height

If no ordering is provided the order is undefined.

(or is it created?)

More examples

?q={"string1":"my-value","number1":99}&orderBy=width&pageSize=10&page=12
?string1=my-value&orderByDescending=string3&page=9

Multiple values

(not yet implemented)

?q={"string1":["a","b"]}

string1 can only take one value per asset, therefore this is interpreted as "assets where string1=a OR string1=b".

?q={"tags":["a","b"]}

tags could have both these values in a single asset, but we still treat this as an OR rather than an AND: "assets that have the tag "a" OR the tag "b" OR both. There is currently no syntax for requesting only assets that have BOTH tags.

?q={"id":["PHOTO.2.22.36.2.tif","other-image.jp2","my-video"]}

id is the internal Model Id (see Identifiers), the last part of the URI. This query returns all assets that match that identifier. If used to filter assets on /customers/{customer}/allImages, the returned assets could be in any of the customer's spaces (but never any other customer), so even a single value for id could return more than one asset. On /customers/{customer}/spaces/{space}/images, each requested id value can only return 0 or 1 assets, because this value must be unique within a space.

touched 2025-09-23T12:04:54