DC 6.1 Getting assets by other properties

URL: /digizuitecore/legacyservice/api/assets/search

Method: POST

Auth required: YES

The search API is extremely flexible in what it can search for, so this page only demonstrates a couple of examples to show the general structure of achieving different results.

You can only get the first 10.000 results by paging through the result using the skip parameter. If you need more, you should use a cursor approach instead. The general trick in the cursor approach is to sort by asset id, then keep track of the last asset id you saw, and request all the assets with an asset id larger/smaller than that. This is very fast and allows you to get all results without missing anything in case the result set changes midway through.

Request properties

Name	Type	Example	Description

Name	Type	Example	Description
sortBy	array of object		Specifies how you want results sorted. Multiple items can be passed in the array to specify sorting criteria in case 2 assets have the same value.
sortBy.searchKey	string	`assetId`	The key of the search field you want to sort on
sortBy.order	enum/string, one of Ascending Descending	`Ascending`	The order you want results sorted in.
facetFields	array of object		Specifies how you want to query for specific value, or how you want faceting results for a UI.
facetFields.searchKey	string	`assetId`	The key of the search field you want to execute this facet on.
facetFields.search	string	`cat`	If you are requesting faceting for this field and not just filtering, then this can be used to search in the facet results instead, in case the value you are looking for is not in the top 10.
facetFields.values	array of string	`["123", "456"]`	Will filter the assets in the result to include this value. Assets that doesn’t have this value will be excluded from the result set.
facetFields.excluded	array of strings	`["789"]`	Will filter the assets in the result to only include assets that doesn’t have this value. If both `excluded` and `values` are specified, `excluded` takes presidence when deciding if an asset should be in the result or not.
facetFields.operation	enum/string, one of Or And	`Or`	If multiple `values` are specified, is it required that the asset has all the value (`And`), or only 1 of them (`Or`).
facetFields.longRange	object		If the field you are faceting on is number-like, this can be used to search for assets with a value in the given range.
facetFields.longRange.from	int64/long	`42`	All assets has to have a value greater than or equals to this.
facetFields.longRange.to	int64/long	`896`	All assets has to have a value less than or equals to this.
facetFields.doubleRange	object		If the field you are searching is a float field, this to be used to search for assets with a value in the given range.
facetFields.doubleRange.from	double	`42.5`	All assets has to have a value greater than or equals to this.
facetFields.doubleRange.to	double	`896.33`	All assets has to have a value less than or equals to this.
facetFields.dateRange	object		If the field you are searching is a datetime field, this to be used to search for assets with a value in the given range.
facetFields.dateRange.from	datetime	`2023-07-03T00:00:00.000`	All assets has to have a value greater than or equals to this.
facetFields.dateRange.to	datetime	`2023-07-07T00:00:00.000`	All assets has to have a value less than or equals to this.
facetFields.facetMode	enum/string, one of Facet QueryOnly		Used to control if facet values are calculated. If you don’t need to render facets in the UI, send `QueryOnly` for better performance.
facetFields.recursive	bool	`true` or `false`	If the field you are searching on is tree like, for example tree metafields or `channelFolder`, this can be used to control if we are only searching for directly that value, or in all “children” of that value too.
facetFields.missingValueHandling	enum/string, one of Irrelevant OnlyShowEmpty HideEmpty		How to deal with assets without a value in the field. Irrelevant: If the value is missing or not doesn’t matter. OnlyShowEmpty: Only assets without a value in the field will be shown. Is mutually exlusive with `values` and `excluded` HideEmpty: Only assets that has a value in the field is included in the search results. Implied if `values` is specified.
facetFields.doubleExactSearchRange	double	`0.01`	If `doubleRange.from` and `doubleRange.to` is specified to the same value, this can be used to control how exact the equality operation is.
facetFields.facetCounts	int	`10`	How many facet values to return when `facetMode` is set to `facet`.
metaFieldItemGuids	array of string/guid/uuid	`6afe78b7-3f24-49f3-bf95-24890ea62696`	Additional metadata that should be included in the asset response. See Get Assets for more information.
freeText	string	`cat\|dog`	Freetext searches on assets. The specifc fields that will be searches on can be controlled using `freeTextOnFields`.
freeTextOnFields	array of string	`6afe78b7-3f24-49f3-bf95-24890ea62696`	The search keys of the fields to execute freetext search on. If not specified the system will search in all text-like fields. If the search value is a valid integer, then `assetId` and `itemId` will also be search.
defaultFreeTextOperation	enum/string, one of Or And	`and`	If there is a space in the freetext query, does that imply `and` or `or` between the value. Recommend value is `and`.
count	int	`12`	How many assets to include in the result.
skip	int	`0` or `100`	How many assets in the result to skip before returning. Can be used to implement paging.
calculateTrueCount	bool	`false` or `true`	If you have more than 10000 matching assets in the result, you will get a total of `10000`. If you pass `true` here, the actual true total number of matching assets will be calculated.

Response properties

Name	Type	Description

Name	Type	Description
errorCode	int	The status code in case something went wrong.
errorMessage	string	An error message in case something wen’t wrong.
hasError	bool	If something went wrong, this will be true.
items	array of objects	Same structure as the Get assets response
total	int	The number of assets that matches the search.
totalRelation	enum/string, one of Eq Gte	Is the `total` number actually equal to the number of search results. `eq` means total matches the number of results. `Gte` means there are more results than the `total` shows.
facets	array of object	Any facetRequest fields that have FacetMode=Facet will be returned here. Again the `type` property should be check to ensure you parse them as the correct subtype.
facets.searchKey	string	The searchkey that was passed in the request. Use it to map between request and response.
facets.fieldName	string	The display name of this search field.
facets.buckets	list of objects	Each bucket is a “facet value”.
facets.buckets.key	string	The value to pass in `facetFields.values/excluded` to search/exclude this value in the result.
facets.buckets.count	int	How many assets has this value.
facets.buckets.label	string/null	A text value to display for this bucket.
facets.buckets.valueObject	object	A details object for this value. For combo value fields this will be the combo value itself. For tree fields the tree value. For ItemReference field this is the item.
facets.min	long/double/datetime/null	The minimum value that occurs for all the assets matching the search.
facets.max	long/double/datetime/null	The maximum value that occurs for all the assets matching the search.
trueTotal	int	If `calculateTrueCount` was specified, then this contains the actual number of matches.

This will simply get the first 12 assets you have access to, sorted by asset id ascending. It will not include any additional facet information.

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search
Authorization: AccessKey MIIC...o0Y=
Content-Type: application/json

{
  "count": 12,
  "skip": 0
}

This will get assets you have access to, that are in the specific channel folder, or any children of that channel folder.

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search
Authorization: AccessKey MIIC...o0Y=
Content-Type: application/json

{
  "facetFields": [
    {
      "facetMode": "QueryOnly",
      "searchKey": "channelFolder",
      "values": [
        "126"
      ],
      "recursive": true
    }
  ],
  "count": 12,
  "skip": 0
}

POST https://<my-dam>/digizuitecore/legacyservice/api/assets/search
Authorization: AccessKey MIIC...o0Y=
Content-Type: application/json

{
  "facetFields": [
    {
      "searchKey": "6afe78b7-3f24-49f3-bf95-24890ea62696",
      "operation": "Or",
      "recursive": false,
      "values": [
        "50178"
      ]
    }
  ],
  "count": 12,
  "skip": 0
}