# Find assets by text, image or filters

Executes a full-text, visual, and/or filtered search over DAM assets and returns matching assets with the requested fields, taxonomies, relations, and renditions.
Use filterable keys and operators that can be discovered with the [DAM Context API](/dam/context-api). For taxonomy and relation filters, use entity `identifier` strings, not numeric IDs or labels. In `include`, use exact key names in their matching section, such as `taxonomies` or `relations`, and `*` is not valid.
The [DAM Context API](/dam/context-api) lists the accepted keys for each section.  Request taxonomy values through `include.taxonomies`. Use taxonomy filters  to select assets by membership.  `total` counts all matches, while `items` contains the page selected by `skip` and `take`.
Taxonomy filters can match values that are not listed in the expanded taxonomy entry. Use an `anyOf` relation filter to find assets linked to  any of the supplied entity identifiers. Full-text search is not an exact  tag-membership test; use the tag taxonomy key to filter for tagged assets.
Use `usageRights` for a permitted-use scenario, with dates in YYYY-MM-DD. Constraints are ANDed within the same combined rights profile; `anyOf` requires at least one listed value, not every value. Omitted constraints are unchecked. Check `capabilities.usageRights` and the advertised keys using the [DAM Context API](/dam/context-api)  before requesting it.
`thumbnailUrl` is always returned when the asset has a thumbnail. `renditions` contains only the rendition keys listed in `include.renditions`; list `thumbnail` there to also receive it under `renditions`. Search returns rendition URLs; dimensions and file size are returned only by asset detail.

Endpoint: POST /api/v1/dam/assets/search
Version: v1.0
Security: OAuth2

## Security:

  - `OAuth2` (unknown)
    oauth2

## Request body:

  - `application/json` (unknown)
    The DAM asset search request payload.

## Request fields (application/json):

  - `query` (object)
    Retrieval inputs used to rank search results.

  - `query.text` (string)
    Free-text query string used to search across indexed content.

  - `query.visual` (object)
    Visual search input payload (mode + value).

  - `query.visual.mode` (string)
    Type of visual search to execute: `asset` (reuse a stored asset's embedding), `image` (absolute HTTP or HTTPS URL), `color` (hex value), or `text` (phrase describing appearance).
    Enum: "asset", "image", "color", "text"

  - `query.visual.value` (string, required)
    Input value for visual search: an asset ID, an absolute HTTP or HTTPS URL, a hex color, or a text phrase.

  - `filters` (array)
    Inclusion criteria; results must match these filter conditions. Entries are ANDed together; values within each entry follow the selected operator.

  - `filters.key` (string, required)
    Context key to evaluate. The key must have `filterable: true` in the DAM Context response.

  - `filters.operator` (string)
    Operator to apply for the filter criterion.
    Enum: "anyOf", "allOf", "between", "greaterThan", "lessThan", "exists"

  - `filters.values` (array)
    The number of values depends on the operator. Supply one or more  values for `anyOf` or `allOf`, two values for between  (minimum and maximum, both inclusive), and one value for `greaterThan`  or `lessThan`. Omit values for `exists`. In filters, exists selects  assets with a value. In exclusions, it selects assets without a value.
For taxonomy and relation filters, use entity `identifier` strings  rather than numeric IDs or display labels.
Use ISO 8601 dates where possible. For date-times, include `Z`  or an explicit timezone offset. Dates without a timezone can also  be accepted. Other formats depend on the server's regional settings,  not the request's culture. Values that cannot be parsed return  `400 INVALID_VALUE`.

  - `exclusions` (array)
    Exclusion criteria; results matching these conditions are filtered out. Supported operators are `anyOf`, `exists`, `greaterThan`, and `lessThan`; `allOf` and `between` are not supported in exclusions.

  - `include` (object)
    Optional response expansion selections for asset search results.

  - `include.fields` (array)
    Canonical field member names to include in response items.

  - `include.taxonomies` (array)
    Canonical taxonomy member names to include in response items.

  - `include.relations` (array)
    Canonical relation member names to include in response items.

  - `include.renditions` (array)
    Rendition keys to include in response items.

  - `usageRights` (object)
    Optional permitted-use scenario, ANDed with ordinary filters and exclusions. Unrestricted assets qualify; restricted assets require no explicit approval and one combined profile covering the dates and supplied constraints. Omitted dimensions are unchecked; `{}` checks today's date only, and omitting `usageRights` performs no rights check. No administrator bypass or download authorization. Requires capabilities.usageRights; otherwise returns 400 USAGE_RIGHTS_UNAVAILABLE (unsupported).
    Example: {"start":"2026-11-01","end":"2026-11-30","constraints":[{"key":"territories","operator":"anyOf","values":["territory-germany","territory-france"]},{"key":"media","operator":"allOf","values":["media-on…

  - `usageRights.start` (string)
    First day, inclusive. Defaults to today's UTC date. Historical dates are allowed; timestamps are rejected.
    Example: 2026-11-01

  - `usageRights.end` (string)
    Last day, inclusive, on or after start. Defaults to the effective start.
    Example: 2026-11-30

  - `usageRights.constraints` (array)
    ANDed within the same combined profile as the dates. Each key occurs at most once.

  - `usageRights.constraints.key` (string, required)
    Canonical key from context usageRights.constraints, not an ordinary asset filter key.

  - `usageRights.constraints.operator` (string, required)
    allOf requires every value; anyOf requires at least one. Multiple constraints can use anyOf, but each must use a different key.
    Enum: "allOf", "anyOf"

  - `usageRights.constraints.values` (array, required)
    Visible canonical taxonomy identifiers of the key's taxonomy, not IDs or labels. Parent coverage includes descendants, not vice versa.

  - `sorting` (object)
    If no `sorting` is provided, requests containing a full-text (`query.text`) or visual (`query.visual`) search are sorted by relevance; all other requests are sorted by `modified_on` descending.

  - `sorting.field` (string, required)
    A sortable context key or `modified_on`. `id` is not supported.

  - `sorting.direction` (string)
    Sort direction.
    Enum: "asc", "desc"

  - `culture` (string)
    Culture/language code used to localize multilingual returned values, for example `en-US`. Defaults to the caller's preferred culture, falling back to `en-US`.

  - `skip` (integer)
    Number of matching results to skip (paging offset).

  - `take` (integer)
    Maximum number of results to return (page size). Maximum allowed is `100`.

## Response 200:

  - `200` (unknown)
    Successful operation

## Response 200 fields (application/json):

  - `culture` (string)
    Effective culture used to localize returned values.

  - `skip` (integer)
    Number of items skipped.

  - `take` (integer)
    Requested number of items.

  - `total` (integer)
    Count of all matches across all pages, not the length of items.

  - `items` (array)
    Current page of matching assets. Use `skip` and `take` to retrieve additional pages.

  - `items.id` (integer)
    Asset entity ID.

  - `items.identifier` (string)
    Asset identifier.

  - `items.title` (string)
    Asset display title.

  - `items.fileName` (string)
    Asset file name.

  - `items.assetType` (any)
    Asset type identifier and localized label.

  - `items.assetType.id` (integer, required)
    Related entity ID.

  - `items.assetType.identifier` (string, required)
    Canonical related entity identifier.

  - `items.assetType.label` (string)
    Display label resolved from the configured display-template properties.  Multilingual properties use the effective culture with `en-US` fallback;  invariant properties use their stored value. Null when no display text can be resolved.

  - `items.mediaType` (any)
    Asset media type identifier and localized label.

  - `items.fileSize` (integer)
    Asset file size in bytes.

  - `items.width` (integer)
    Asset width in pixels.

  - `items.height` (integer)
    Asset height in pixels.

  - `items.createdOn` (string)
    Asset creation timestamp.

  - `items.lifecycleStatus` (any)
    Asset lifecycle status identifier and localized label.

  - `items.thumbnailUrl` (string)
    Primary thumbnail URL for the asset. Always returned when the asset has a thumbnail, independent of `include.renditions`.

  - `items.description` (string)
    Asset description.

  - `items.fields` (object)
    Custom property values requested in `include.fields`, keyed by the exact member key requested. Multilingual values are resolved to the effective culture and are omitted when that culture has no value; other values keep their stored JSON type. A requested key the asset does not carry is omitted. Empty when `include.fields` is not sent.

  - `items.taxonomies` (object)
    Requested taxonomy values keyed by canonical member name.

  - `items.relations` (object)
    Related entity references grouped by canonical relation key.

  - `items.renditions` (object)
    Rendition metadata keyed by rendition name, limited to the keys requested in `include.renditions`. `thumbnail` appears here only when requested; `thumbnailUrl` carries its URL either way.

## Response 400:

  - `400` (unknown)
    Facade validation failures use ErrorResponse. Framework model-state failures use a parameter-to-messages dictionary. USAGE_RIGHTS_UNAVAILABLE (category unsupported, not retryable) means a usageRights scenario was requested while capabilities.usageRights is false. Recover via the [DAM Context API](/dam/context-api).  An invalid usage-rights key, operator, identifier, date or constraint returns UNKNOWN_FILTER, UNSUPPORTED_OPERATOR or INVALID_VALUE with the full parameter path, for example `usageRights.constraints[0].values[0]`.

## Response 400 fields (application/problem+json):

  - `type` (string)
    Generic RFC 7231 status-code reference, shared across codes. Never branch on this; branch on `code`.

  - `title` (string)
    Stable per `code`.

  - `status` (integer, required)

  - `detail` (string)
    Occurrence-specific explanation.

  - `instance` (string)
    The request path that produced this occurrence.

  - `code` (string, required)
    Stable identifier. Never reworded or renumbered once shipped. Search validation codes: `INVALID_VALUE`, `UNKNOWN_FILTER`, `NOT_FILTERABLE`, `UNSUPPORTED_OPERATOR`, `UNRESOLVED_FILTER`, `UNKNOWN_INCLUDE`, `UNKNOWN_SORT`, `NOT_VISUALLY_INDEXED`, and `USAGE_RIGHTS_UNAVAILABLE`. GET-by-ID validation uses `INVALID_VALUE` or `UNKNOWN_INCLUDE`; missing or invisible assets return `ASSET_NOT_FOUND`. Search service failures use `VISUAL_SEARCH_UNAVAILABLE` or `SERVICE_UNAVAILABLE`. Unhandled endpoint failures use `INTERNAL_ERROR`. Authentication, authorization, and platform throttling errors are handled separately.

  - `category` (string)
    Omitted for timeout, rate-limit, dependency, or internal failures.
    Enum: "auth", "precondition", "not_found", "ambiguous", "validation", "conflict", "policy", "unsupported"

  - `requiredNextStep` (object)
    A suggested API request to resolve the error, when available. Invalid taxonomy values link to the corresponding taxonomy-value lookup. Usage-rights availability and other validation failures link to the [DAM Context API](/dam/context-api). An invalid asset ID links to asset search.

  - `requiredNextStep.operationId` (string, required)

  - `requiredNextStep.method` (string, required)
    Enum: "GET", "POST", "PUT", "PATCH", "DELETE"

  - `requiredNextStep.href` (string, required)

  - `requiredNextStep.reason` (string, required)

  - `errors` (object)
    Parameter name to human-readable messages.

  - `invalidParams` (array)

  - `invalidParams.parameter` (string)

  - `invalidParams.value` (string)
    The offending value as received, when applicable.

  - `invalidParams.reason` (string)
    Enum: "no_match", "ambiguous", "wrong_taxonomy", "unparseable", "operator_not_supported", "not_filterable", "out_of_range"

  - `invalidParams.candidates` (array)

  - `traceId` (string)

## Response 401:

  - `401` (unknown)
    Handled by existing authentication before endpoint access checks. These endpoints do not define or change the authentication error body.

## Response 403:

  - `403` (unknown)
    Access denied after successful authentication. Never returned for a malformed request.

## Response 403 fields (application/problem+json):

  - `type` (string)
    Generic RFC 7231 status-code reference, shared across codes. Never branch on this; branch on `code`.

  - `title` (string)
    Stable per `code`.

  - `status` (integer, required)

  - `detail` (string)
    Occurrence-specific explanation.

  - `instance` (string)
    The request path that produced this occurrence.

  - `code` (string, required)
    Stable identifier. Never reworded or renumbered once shipped. Search validation codes: `INVALID_VALUE`, `UNKNOWN_FILTER`, `NOT_FILTERABLE`, `UNSUPPORTED_OPERATOR`, `UNRESOLVED_FILTER`, `UNKNOWN_INCLUDE`, `UNKNOWN_SORT`, `NOT_VISUALLY_INDEXED`, and `USAGE_RIGHTS_UNAVAILABLE`. GET-by-ID validation uses `INVALID_VALUE` or `UNKNOWN_INCLUDE`; missing or invisible assets return `ASSET_NOT_FOUND`. Search service failures use `VISUAL_SEARCH_UNAVAILABLE` or `SERVICE_UNAVAILABLE`. Unhandled endpoint failures use `INTERNAL_ERROR`. Authentication, authorization, and platform throttling errors are handled separately.

  - `category` (string)
    Omitted for timeout, rate-limit, dependency, or internal failures.
    Enum: "auth", "precondition", "not_found", "ambiguous", "validation", "conflict", "policy", "unsupported"

  - `requiredNextStep` (object)
    A suggested API request to resolve the error, when available. Invalid taxonomy values link to the corresponding taxonomy-value lookup. Usage-rights availability and other validation failures link to the [DAM Context API](/dam/context-api). An invalid asset ID links to asset search.

  - `requiredNextStep.operationId` (string, required)

  - `requiredNextStep.method` (string, required)
    Enum: "GET", "POST", "PUT", "PATCH", "DELETE"

  - `requiredNextStep.href` (string, required)

  - `requiredNextStep.reason` (string, required)

  - `errors` (object)
    Parameter name to human-readable messages.

  - `invalidParams` (array)

  - `invalidParams.parameter` (string)

  - `invalidParams.value` (string)
    The offending value as received, when applicable.

  - `invalidParams.reason` (string)
    Enum: "no_match", "ambiguous", "wrong_taxonomy", "unparseable", "operator_not_supported", "not_filterable", "out_of_range"

  - `invalidParams.candidates` (array)

  - `traceId` (string)

## Response 429:

  - `429` (unknown)
    Rate limited by the platform throttling middleware when throttling is enabled for the environment. The body is a plain-text message, not an ErrorResponse. Retry after the `Retry-After` header.

## Response 429 headers (text/plain):

  - `Retry-After` (integer)
    Seconds to wait before retrying.

## Response 500:

  - `500` (unknown)
    Internal error.

## Response 500 fields (application/problem+json):

  - `type` (string)
    Generic RFC 7231 status-code reference, shared across codes. Never branch on this; branch on `code`.

  - `title` (string)
    Stable per `code`.

  - `status` (integer, required)

  - `detail` (string)
    Occurrence-specific explanation.

  - `instance` (string)
    The request path that produced this occurrence.

  - `code` (string, required)
    Stable identifier. Never reworded or renumbered once shipped. Search validation codes: `INVALID_VALUE`, `UNKNOWN_FILTER`, `NOT_FILTERABLE`, `UNSUPPORTED_OPERATOR`, `UNRESOLVED_FILTER`, `UNKNOWN_INCLUDE`, `UNKNOWN_SORT`, `NOT_VISUALLY_INDEXED`, and `USAGE_RIGHTS_UNAVAILABLE`. GET-by-ID validation uses `INVALID_VALUE` or `UNKNOWN_INCLUDE`; missing or invisible assets return `ASSET_NOT_FOUND`. Search service failures use `VISUAL_SEARCH_UNAVAILABLE` or `SERVICE_UNAVAILABLE`. Unhandled endpoint failures use `INTERNAL_ERROR`. Authentication, authorization, and platform throttling errors are handled separately.

  - `category` (string)
    Omitted for timeout, rate-limit, dependency, or internal failures.
    Enum: "auth", "precondition", "not_found", "ambiguous", "validation", "conflict", "policy", "unsupported"

  - `requiredNextStep` (object)
    A suggested API request to resolve the error, when available. Invalid taxonomy values link to the corresponding taxonomy-value lookup. Usage-rights availability and other validation failures link to the [DAM Context API](/dam/context-api). An invalid asset ID links to asset search.

  - `requiredNextStep.operationId` (string, required)

  - `requiredNextStep.method` (string, required)
    Enum: "GET", "POST", "PUT", "PATCH", "DELETE"

  - `requiredNextStep.href` (string, required)

  - `requiredNextStep.reason` (string, required)

  - `errors` (object)
    Parameter name to human-readable messages.

  - `invalidParams` (array)

  - `invalidParams.parameter` (string)

  - `invalidParams.value` (string)
    The offending value as received, when applicable.

  - `invalidParams.reason` (string)
    Enum: "no_match", "ambiguous", "wrong_taxonomy", "unparseable", "operator_not_supported", "not_filterable", "out_of_range"

  - `invalidParams.candidates` (array)

  - `traceId` (string)

## Response 503:

  - `503` (unknown)
    Visual search unavailable, or the service is temporarily unable to serve the request. A failure that prevents applying a requested usageRights scenario returns SERVICE_UNAVAILABLE, never unfiltered results.

## Response 503 fields (application/problem+json):

  - `type` (string)
    Generic RFC 7231 status-code reference, shared across codes. Never branch on this; branch on `code`.

  - `title` (string)
    Stable per `code`.

  - `status` (integer, required)

  - `detail` (string)
    Occurrence-specific explanation.

  - `instance` (string)
    The request path that produced this occurrence.

  - `code` (string, required)
    Stable identifier. Never reworded or renumbered once shipped. Search validation codes: `INVALID_VALUE`, `UNKNOWN_FILTER`, `NOT_FILTERABLE`, `UNSUPPORTED_OPERATOR`, `UNRESOLVED_FILTER`, `UNKNOWN_INCLUDE`, `UNKNOWN_SORT`, `NOT_VISUALLY_INDEXED`, and `USAGE_RIGHTS_UNAVAILABLE`. GET-by-ID validation uses `INVALID_VALUE` or `UNKNOWN_INCLUDE`; missing or invisible assets return `ASSET_NOT_FOUND`. Search service failures use `VISUAL_SEARCH_UNAVAILABLE` or `SERVICE_UNAVAILABLE`. Unhandled endpoint failures use `INTERNAL_ERROR`. Authentication, authorization, and platform throttling errors are handled separately.

  - `category` (string)
    Omitted for timeout, rate-limit, dependency, or internal failures.
    Enum: "auth", "precondition", "not_found", "ambiguous", "validation", "conflict", "policy", "unsupported"

  - `requiredNextStep` (object)
    A suggested API request to resolve the error, when available. Invalid taxonomy values link to the corresponding taxonomy-value lookup. Usage-rights availability and other validation failures link to the [DAM Context API](/dam/context-api). An invalid asset ID links to asset search.

  - `requiredNextStep.operationId` (string, required)

  - `requiredNextStep.method` (string, required)
    Enum: "GET", "POST", "PUT", "PATCH", "DELETE"

  - `requiredNextStep.href` (string, required)

  - `requiredNextStep.reason` (string, required)

  - `errors` (object)
    Parameter name to human-readable messages.

  - `invalidParams` (array)

  - `invalidParams.parameter` (string)

  - `invalidParams.value` (string)
    The offending value as received, when applicable.

  - `invalidParams.reason` (string)
    Enum: "no_match", "ambiguous", "wrong_taxonomy", "unparseable", "operator_not_supported", "not_filterable", "out_of_range"

  - `invalidParams.candidates` (array)

  - `traceId` (string)

