Skip to main content
Scroll to top

Keepeek - Getting started: Advanced search

Lucas Simon
Updated

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:

  1. Create an advanced search through the API
    Alternate option: create an advanced search through the Back-office application.
     
  2. 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:
"statuses": [
  "ONLINE",
  "OFFLINE",
  "PENDING_TO_ONLINE"
]

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

 

Related articles

Comments

0 comments

Please sign in to leave a comment.