Create a search - Fluid Topics

This web service creates a new search and stores it in the user's library.

Method	Endpoint
`POST`	`/api/users/{userId}/searches`

Path parameter	Type	Description
`{userId}`	String	The user's identifier. See the List users or Search users web services to find a user's ID. It is also possible to get a user's ID from the Manage users menu.

Request example

The following lines show an example of a JSON response body:

{
  "title": "My new search",
  "description": "Searching for topics about xyz",
  "color": "orange",
  "alert": true,
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz",
    "metadataFilters": [
      {
        "key": "ft:editorialType",
        "valueFilter": {
          "values": [
            "book"
          ],
          "negative": false
        }
      },
      {
        "key": "author",
        "rangeFilter": {
          "from": "2022-07-08",
          "to": "2023-10-13"
        }
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ]
  }
}

Field	Type	Required?	Description
`title`	String	Yes	The title of the saved search.
`description`	String	Yes	The description of the saved search.
`color`	String	Yes	A color for the saved search's tag. Accepted values are `black`, `green`, `blue`, `purple`, `red`, `orange`, and `yellow`.
`alert`	Boolean	No	A boolean indicating whether to activate an alert for the search. Possible values are `true` or `false`.
`searchRequest`	Object	Yes	The parameters of the saved search.
`contentLocale`	String	Yes	Defines the language of the search results.
`query`	String	No	The terms of the search query.
`metadataFilters`	Array	No	Filters the results based on selected criteria including metadata and date ranges. Defaults to an empty list.
`key`	String	Yes	Expects a metadata key.
`valueFilter`	Object	No	Contains the filtering conditions based on metadata values.
`values`	Array	Yes	Defines the value for the selected key. When multiple values are defined, they are combined with an `AND` or an `OR` operator depending on the tenant's configuration.
`negative`	Boolean	No	When `true`, this parameter excludes results matching the previously defined values. By default, the `negative` parameter is implicit and `false`.
`dateFilter`	Object	No	Specifies the date-based filtering conditions using predefined periods.
`type`	String	Yes	Restricts results to those within a predefined period. Acceptable values are `LAST_WEEK`, `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`.
`rangeFilter`	Object	No	Specifies custom date range filtering.
`from`	String	Yes	The inclusive start date of the period. If unspecified, the default value is `1970-01-01`.
`to`	String	Yes	The inclusive end date of the period. If unspecified, the default value is the current day.
`sort`	Array	No	Specifies if search results should be sorted based on certain criteria.
`type`	String	No	The sorting method to be applied to search results. Possible values are `ALPHA` (lexicographic order) and `NATURAL` (natural sort order).
`key`	String	No	An element prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	No	Defines the sort order. Possible values are `ASC` and `DESC`.

Return code	Description
`201 CREATED`	The saved search was created and added to the user's library.
`400 BAD REQUEST`	A required parameter is missing or an invalid color was provided for the saved search's tag.
`401 UNAUTHORIZED`	The authorization header is absent or invalid.
`403 FORBIDDEN`	The user or API key does not have the `USERS_ADMIN` or `ADMIN` role, or the user corresponding to the USER_ID parameter does not have the `SAVED_SEARCH_USER` role.
`404 NOT FOUND`	No user exists with this ID.

For a comprehensive list of all possible return codes, see Return codes.

Response body

The following lines show an example of a JSON response body:

{
  "ownerId": "24502ba6-a2da-4db8-8ec1-c8d29f970454",
  "id": "a393cb2q-3070-4aaf-a134-917e154b4ceb",
  "title": "My new search",
  "description": "Searching for topics about xyz",
  "color": "orange",
  "alert": true,
  "searchRequest": {
    "contentLocale": "en-US",
    "query": "xyz",
    "filters": [
      {
        "key": "ft:editorialType",
        "label": "ft:editorialType",
        "values": [
          "book"
        ],
        "negative": false
      }
    ],
    "metadataFilters": [
      {
        "key": "ft:editorialType",
        "valueFilter": {
          "values": [
            "book"
          ],
          "negative": false
        }
      },
      {
        "key": "Product",
        "rangeFilter": {
          "from": "2022-07-08",
          "to": "2023-10-13"
        }
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "key": "Product",
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2022-10-13"
      }
    }
  },
  "creationDate": "2023-10-22T15:10:07.126+00:00"
}

Field	Type	Description
`ownerId`	String	The identifier of the user who owns the saved search.
`id`	String	The identifier of the saved search.
`title`	String	The title of the saved search.
`description`	String	The description of the saved search.
`color`	String	A color for the saved search's tag. Accepted values are `black`, `green`, `blue`, `purple`, `red`, `orange`, and `yellow`.
`alert`	Boolean	A boolean indicating whether to activate an alert for the search. Possible values are `true` or `false`.
`searchRequest`	Object	The parameters of the saved search.
`contentLocale`	String	Indicates the language of the search results.
`query`	String	The terms of the search query.
`filters`	Array	The filters applied to the search query.
`key`	String	The filter's metadata key.
`values`	Array	A list of values for the metadata key.
`metadataFilters`	Array	Filters applied to the search query based on metadata values and date ranges.
`key`	String	The filter's metadata key.
`valueFilter`	Object	Contains conditions based on metadata values.
`values`	Array	A list of values for the metadata key.
`negative`	Boolean	Excludes results matching the specified `values` when `true`. Defaults to `false`.
`dateFilter`	Object	Specifies the date-based filtering conditions using predefined periods.
`type`	String	Restricts results to those within a predefined period. Acceptable values are `LAST_WEEK`, `LAST_MONTH`, `LAST_QUARTER`, `LAST_YEAR`.
`rangeFilter`	Object	Specifies custom date range filtering.
`from`	String	The start date of the period used to filter the search results.
`to`	String	The end date of the period used to filter the search results.
`sort`	Array	Indicates if search results should be sorted based on certain criteria.
`key`	String	An element prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	Defines the sort order. Possible values are `ASC` and `DESC`.
`type`	String	The sorting method to be applied to search results. Possible values are `ALPHA` (lexicographic order) and `NATURAL` (natural sort order).
`periodFilter`	Object	Filters search results by period.
`key`	String	The filter's metadata key.
`periodType`	String	Defines the type of period by which to filter the search results. Possible values include `LAST_WEEK`,`LAST_MONTH`, `LAST_YEAR` and `CUSTOM`.
`period`	Object	Defines the period by which to filter the search results.
`from`	String	The start date of the period.
`to`	String	The end date of the period.
`creationDate`	String	The date when the saved search was created.

The filters and periodFilter arrays are deprecated. Use the metadataFilters array instead. It combines the values of both arrays.

Create a search - Fluid Topics - Latest

Fluid Topics API Reference Guide