Search and filter parameters

You can extend a query by adding attributes, which cause the results of that query to be limited to specific keywords; sorted in a specific order; or filtered by criteria such as file size, edit date, or content type. Doing this can give you more precise search results than those returned using the app.

Supported query attributes include:

For a full list of supported query attributes, see the data model or the Content Management API Swagger reference file. For guidance on API syntax, see Syntax and, for a list of endpoints, see Content Management API.

You can query content, content types, and media using a keyword, and extend the query using operators.

Keyword

A query that includes a keyword search examines the name, item ID, and all other text fields for a string of text (for example, apple). This string must be at least three characters long and contain one or more specific keywords. A search for apple pie is the same as a search for apple AND pie. The order of the keywords in the string is not important so a search for apple pie and pie apple bring up the same results. How results are ordered may differ, however, because the first term is given more weight than subsequent terms.

Keyword searches use the StartsWith wildcard mode, meaning that each search term is treated as the start of a word. This has the same effect as entering a term followed by an asterisk, such as app*, and returns values such as app, apple, apparel, and so on. If the search includes multiple terms, each one is treated as the start of a word, so searching for apple pie returns apple pie, apple pies, apple pieces, and so on. To match your query, the result must include at least one word starting with each of the search terms, so searching for apple pie would not return results that contain only apple, or only pie, and not both.

Example

RequestResponse
 <Base_URL>/api/content/v1/items/?search=apple pie

A keyword search can include a wildcard, which increases the scope of the search by fetching results that match a specified pattern, instead of a literal term. In the first example, the search returns results containing at least one word ending with able, such as affable or probable. In the second example, the results must include at least one five-letter word ending with able, such as fable or table:

Examples

RequestResponse
 <Base_URL>/api/content/v1/items/?search=*able
 <Base_URL>/api/content/v1/items/?search=?able

Operators

A search query can include the AND operator and the OR operator.

Examples

RequestResponse
 <Base_URL>/api/content/v1/items/?search=apples AND oranges
RequestResponse
 <Base_URL>/api/content/v1/items/?search=apples OR pears
Note

The operator must be uppercase with a space on either side.

Sort

Query results can be sorted according to various attributes, depending on the type of data being queried. This is done using the SortBy parameter. When you give this parameter an attribute as its value, the results are sorted in ascending order based on that attribute.

In the following example, the query results are sorted in alphabetical order based on the name attribute.

RequestResponse
 <Base_URL>/api/content/v1/media/?search=apples AND oranges&sortBy=name

To sort results in descending order instead, put a ! in front of the attribute.

RequestResponse
 <Base_URL>/api/content/v1/media/?search=apples AND oranges&sortBy=!name

The following table lists each of the available APIs alongside the attributes that can be used to sort the results of queries to those APIs.

API

SortBy

Content types

  • system.createdAt

  • system.updatedAt

  • name

Content items

  • system.status

  • system.createdAt

  • system.updatedAt

  • system.publishedAt

  • name

Media items

  • system.status

  • system.createdAt

  • system.updatedAt

  • system.publishedAt

  • name

Taxonomies

Not yet supported

Filter

You can reduce the number of query results using filters. The types of filter available depend on the item type. The following table lists each of the available APIs alongside the attributes that can be used to filter the results of queries to those APIs.

API

Filter

Filter examples

Content types

Not yet supported

N/A

Content items

  • system.status

  • system.createdAt

  • system.primary

  • system.sourceLocale

  • system.updatedAt

  • system.publishedAt

  • system.contentType.id

  • system.locale

  • id

  • name

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.status=published

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.createdAt=2023-06-12

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.primary

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.sourceLocale

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.updatedAt= 2022-10-29

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.publishedAt= 2023-06-12

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.locale=fr-CA

    You can also filter items where the locale is null - system.locale=null

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?system.contentType.id=artist

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?id=<contentItemId>

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?name=pink-couch.jpg

Taxonomies

  • taxonomy value

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/items/?taxonomy[{:placeholder-token:}<TAXONOMY_ID>{/:placeholder-token:}]={:placeholder-token:}<TAXONOMY_VALUE>{/:placeholder-token:}

Locales

Not yet supported

N/A

Media items

  • system.status

  • system.createdAt

  • system.updatedAt

  • system.publishedAt

  • id

  • name

  • file.type

  • file.size

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?file.type=image/jpeg&status=Draft

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?system.createdAt=2023-06-12

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?system.updatedAt= 2022-10-29

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?system.publishedAt= 2023-06-12

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?id={contentItemId}

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?name=pink-couch.jpg

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?file.type=image/jpeg/image/png

  • {:placeholder-token:}<Base_URL>{/:placeholder-token:}/api/content/v1/media/?file.size= 200&file.size= 1000

Note

With filters, you can use a pipe (|) to denote OR and an ampersand (&) to denote AND. Nested OR and AND operators are not supported.

Pagination

You can apply pagination to query results using the following query parameters:

  • pageNumber - returns a specific page. The default is 1.

  • pageSize - returns a specific number of results per page. The default is 20. The maximum is 100.

Examples

RequestResponse
 <Base_URL>/api/content/v1/taxonomies/?pageSize=5
RequestResponse
 <Base_URL>/api/content/v1/media/?file.type=image/jpeg&pageSize=100&pageNumber=3
RequestResponse
 <Base_URL>/api/content/v1/items?search=hotel&sortBy=!system.updatedAt&pageNumber=2

Do you have some feedback for us?

If you have suggestions for improving this article,