Keepeek - Getting started: Advanced search
When simple search is not enough for your needs, here comes the advanced search!
The advanced search allows you to create complex queries to research your medias through the assets library.
In 2 steps:
- Create an advanced search through the API
Alternate option: create an advanced search through the Back-office application.
- Execute the advanced search through the API
1. Create an advanced search
An advanced search is composed of different filters.
To discover which filters you can use, you can execute a GET request on the path /api/dam/search/advanced/criterias :
curl --request GET \
--url https://{{KeepeekInstance}}/api/dam/search/advanced/criterias \
--header 'authorization: Basic baseEncodedLoginPassword=='
You will receive a paginated collection of criteria:
{
"internalFieldName": "internalName",
"availableModifiers": [
"EQUALS_ONE",
"EMPTY",
"NOT_EMPTY",
"CONTAINS_ONE",
"CONTAINS_NONE"
],
"type": "TEXTFIELD",
"fieldType": "METAFIELD",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/search/advanced/criterias/internalName"
},
"kpk:sheet-field": {
"href": "https://{{KeepeekInstance}}/api/dam/sheet-fields/title"
}
}
}
As you can see, a criteria has 4 main fields:
- InternalName: The name by which you can identify it
- avalableModifiers: The modifier you can use to build your queries*
- type: The type of the field**
- fieldType: indicate whether it is a field belonging to the media (MEDIAFIELD) or a field belonging to a media sheet (METAFIELD).
In order to create an advanced search, you have do a POST request on the path /api/dam/search/advanced with a body containing a list of filters with values.
Here i want to create a search to find the medias with the title "test" (in French) that were uploaded today.
You can see that for the title, there is an array values. This array values can be an array of number or string depending of the context (More on this topic later):
curl --request POST \
--url https://{{KeepeekInstance}}/api/dam/search/advanced \
--header 'authorization: Basic baseEncodedLoginPassword==' \
--header 'content-type: application/json' \
--data '{
"_embedded": {
"filter": [
{
"internalFieldName": "title.FR",
"modifier": "EQUALS_ONE",
"values": ["test"],
"type": "TEXTFIELD",
"fieldType": "METAFIELD"
},
{
"internalFieldName": "importDate",
"modifier": "DATE_TODAY",
"type": "DATEFIELD",
"fieldType": "MEDIAFIELD"
}
]
}
}'
you should receive a response :
{
"id": "{{advancedSearchId}}",
"type": "TEMPORARY",
"expirationDate": "2025-04-10T16:52:33.000Z",
"_links": {
"self": {
"href": "/api/dam/search/advanced/{{advancedSearchId}}"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
],
"kpk:medias": {
"href": "/api/dam/search/advanced/{{advancedSearchId}}/media"
}
},
"_embedded": {
"filter": [
{
"internalFieldName": "title.FR",
"modifier": "EQUALS_ONE",
"type": "TEXTFIELD",
"fieldType": "METAFIELD",
"saveValues": true,
"values": [
"test"
]
},
{
"internalFieldName": "importDate",
"modifier": "DATE_TODAY",
"type": "DATEFIELD",
"fieldType": "MEDIAFIELD",
"saveValues": true,
"values": []
}
]
}
}
You can see that your filters are saved, but more important, there is a kpk:medias link in the _links section.
NB: Advanced search created through the API have an expiration date, and might be automatically removed. The expiration date is not guaranteed by the API as temporary resources may be wiped out for maintenance purpose.
2. Execute the advanced search
By executing a GET request on the kpk:medias link, you should receive the results media of your research.
curl --request GET \
--url 'https://{{KeepeekInstance}}/api/dam/search/advanced/30rm6aix/media?fields=id' \
--header 'authorization: Basic baseEncodedLoginPassword=='
You should receive a response of this form, here I have one media corresponding to my search:
{
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/search/advanced/30rm6aix/media?page=1&size=20"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
]
},
"_embedded": {
"media": {
"id": 8815,
"title": "test",
"statusUpdateDate": "2025-04-10T14:51:51.000Z",
"permission": "ADMIN",
"mediaType": "image/jpeg",
"fileSize": 3263762,
"fileSizeString": "3,3 Mo",
"updateDate": "2025-04-10T14:53:05.000Z",
"duplicationStatus": "NO_DUPLICATES",
"thumbnailGenerationStatus": "GENERATED",
"attachmentCounts": {
"online": 0,
"offline": 0,
"pendingToOnline": 0
},
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/medias/8815"
},
"kpk:large": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-large.jpg"
},
"kpk:medium": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-medium.jpg"
},
"preview": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-preview.jpg"
},
"kpk:small": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-small.jpg"
},
"kpk:tech": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-tech.jpg"
},
"kpk:whr": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-whr.jpg"
},
"kpk:xlarge": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-xlarge.jpg"
},
"kpk:zoom": {
"href": "https://static.{{KeepeekInstance}}/medias/domain1/media100029/8815-4fxi93aqyt-zoom.jpg"
}
}
}
},
"totalCount": 1
}
Note that as the simple search, the advanced search also supports the fields parameter with partial response, and the size parameters. Then the optimizations described in the best practices search page is valid here. So I could ask for only the id,the title and the self of the medias.
curl --request GET \
--url 'https://{{KeepeekInstance}}/api/dam/search/advanced/30rm6aix/media?fields=id,title,_links{self}' \
--header 'authorization: Basic baseEncodedLoginPassword=='
And I receive the much less longer response containing only the id, title and self link of each media:
{
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/search/advanced/30rm6aix/media?fields=id%2Ctitle%2C_links%7Bself%7D&page=1&size=20"
},
"curies": [
{
"name": "kpk",
"href": "https://{{KeepeekInstance}}/api/doc/rels/{rel}",
"templated": true
}
]
},
"_embedded": {
"media": {
"id": 8815,
"title": "test",
"_links": {
"self": {
"href": "https://{{KeepeekInstance}}/api/dam/medias/8815"
}
}
}
},
"totalCount": 1
}
Alternate option: Create an advanced search through the Back-office application
As you can see, creating an advanced search can be quite difficult for a beginner. If your use case it to always use the same advanced search without any modification, then you could create it with UI and use it in the API! Let's see how to do this.
First, go to the Advanced search menu:
Display all criterias to see what you can search:
Then add all the filters you want, here I am creating the same advanced search as I did earlier:
Then you can save your advanced search by going to options and save:
Add a title to you search and save it:
Your advanced search is now saved indefinitely and not temporary. We can now go find it in the API with the /api/dam/search/advanced/ path.
Warning: when you create an advanced search, by default it is only available for the user who created the search. In order to change this behavior, you can share this search with other users. Let's see how to do this.
Go the advanced search Options tab:
Go to Manage my searches tab:
Go to the sharing tab:
You can now share the advanced search with everyone or a restricted group of user:
Here is the exhaustive documentation for advanced search (French only)
* All available modifiers:
| Modifier | Description |
|---|---|
| EQUALS | Field value is strictly equals to |
| EQUALS_ONE | Field value is strictly equals to one of the values |
| CONTAINS_ONE | (Multivalue) Field value contains one of the values |
| CONTAINS_ALL | (Multivalue) Field value contains all the values |
| CONTAINS_NONE | (Multivalue) Field value does not contain any of the values |
| BEGINS_WITH | Text field begins with value |
| ENDS_WITH | Text field ends with value |
| EQUALS_NO_VALUES | Field value is strictly different from any value |
| FROM_TO | Numeric/Date field value is in range FROM-TO |
| EMPTY | Field is empty |
| NOT_EMPTY | Field is not empty |
| DATE_TODAY | Date field value is equals to today (at the time the search is executed) |
| DATE_YESTERDAY | Date field value is equals to yesterday (at the time the search is executed) |
| DATE_LAST_7_DAYS | Date field value is equals to any date in the last 7 days (at the time the search is executed) |
| DATE_LAST_30_DAYS | Date field value is equals to any date in the last 30 days (at the time the search is executed) |
| DATE_LAST_MONTH | Date field value is equals to any date in previous calendar month (at the time the search is executed) |
| DATE_CURRENT_MONTH | Date field value is equals to any date in current calendar month (at the time the search is executed) |
| GROUP_CONTAINS_ONE | Users/Group value is one of the group ids |
| GROUP_CONTAINS_NONE | Users/Group value is none of the group ids |
| DATE_UPCOMING_DAYS | Date field value is equals to any date in the requested next days |
| DATE_FROM_TO_UPCOMING_DAYS | Data field is contained in the days the configured days interval |
Type of fields
| Type | Description | Values format |
|---|---|---|
| TEXTFIELD | Field that represents a text | array of string |
| EMAILFIELD | Field that represents an email | array of string |
| URLFIELD | Field that represents an URL | array of string |
| TEXTAREA | Field that represents a long text | array of string |
| DATEFIELD | Field that represents a date |
array of string with a date format (RFC 3339 §5.6 date/time format String representation (ie "2019-11-13T21:33:45+0200" )). Only the date will be kept because it is a date field. or array of number, depending on the modifier*. |
| THESAURUSFIELD | Field that represents a thesaurus | array of number that represent thesauruses ids |
| CHECKBOXFIELD | Field that represents a checkbox | array of one boolean |
| NUMBERFIELD | Field that represents a number | array of numbers |
| LISTFIELD | Field that represents value of field | array of string |
| GEOFIELD | Field that represents a position | array of string |
| MULTIPLELISTFIELD | Field that represent a list of choice like a dropdown list | Array of numbers |
| DATETIMEFIELD | Field that represents a date and time object |
array of string with a date format (RFC 3339 §5.6 date/time format String representation (ie "2019-11-13T21:33:45+0200" )). or array of number, depending on the modifier*. |
| EXTENSIONFIELD | Field that represents a file extension | array of string |
| STATUSFIELD | Field that represents a media status | array of number that represent statuses ids |
| FOLDERFIELD | Field that represents a folder | array of number that represent folders ids |
| METAMODELTYPEFIELD | Field that represents type of media sheet | Array of number that represent medtamodel type ids |
| METAMODELFIELD | Field that represents a media sheet | Array of number that represent metamodel field ids |
| USERSFIELD | Field that represent user ids | Array of numbers |
| TAGSFIELD | Field that represents tags | Array of numbers |
| DURATIONFIELD | Field that represents a duration [] | |
| ATTACHMENTSFIELD | Field that represent type of attachments |
Array of one value that has the format: You can choose between the three statuses |
| SEARCHFULLTEXTFIELD | Special field to apply full text research | Array of string |
| MEDIALINKEDFIELD | Field that represent linked media | Array of integer |
| POIDEFINEDFIELD | Field that represents if there is a point of interest | Array of one boolean |
* DATEFIELD and DATETIMEFIELD values depending of modifier:
| Modifier | Format of the value |
| FROM_TO | Date field values (array of two dates) is in range FROM-TO |
|
DATE_TODAY DATE_YESTERDAY DATE_LAST_30_DAYS DATE_LAST_MONTH DATE_CURRENT_MONTH |
no value |
|
DATE_UPCOMING_DAYS DATE_FROM_TO_UPCOMING_DAYS |
number |