Update a search - Fluid Topics

This web service updates a saved search that was previously added to the user's library.

Method	Endpoint
`PUT`	`/api/users/{userId}/searches/{searchId}`

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.
`{searchId}`	String	The search's identifier as retrieved when listing all searches.

Request example

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

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

Field	Type	Required?	Description
`title`	String	No	The title of the saved search.
`description`	String	No	The description of the saved search.
`color`	String	No	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	No	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	Indicates 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`.

While the title, description, color, alert and searchRequest parameters are all optional, it is necessary to specify at least one of these parameters in the request.
Only parameters included in the query are updated. Parameters not included in the query remain unchanged.

Return code	Description
`200 OK`	The saved search was updated.
`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.
`404 NOT FOUND`	No user exists with this identifier.

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 updated search",
  "description": "Updated search about xyz",
  "color": "orange",
  "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": "period",
        "rangeFilter": {
          "from": "2022-07-08",
          "to": "2023-10-13"
        }
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "key": "period",
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2022-10-13"
      }
    }
  },
  "alert": true,
  "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.

Update a search - Fluid Topics - Latest

Fluid Topics API Reference Guide