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.
`{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" ,
    "filters": [
      {
        "key": "ft:editorialType",
        "values": ["book"],
        "negative": false
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2022-10-13"
      }
    }
  }
}

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.
`filters`	Array	No	The filters applied to the search query.
`key`	String	Yes	The filter's metadata key.
`values`	Array	Yes	A list of values for the metadata key.
`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` and `NATURAL`.
`key`	String	No	An element prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	String	No	An element that defines the sort order. Possible values are `ASC` and `DESC`.
`periodFilter`	Object	No	An optional element of the `searchRequest` parameter that filters search results by period.
`periodType`	String	Yes	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	No	Defines the start and end of the period by which to filter the search results.
`from`	String	Yes	The start date of the period by which to filter the search results.
`to`	String	Yes	The end date of the period by which to filter the search results.

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",
        "values": "book",
        "negative": false
      }
    ],
    "sort": [
      {
        "type": "NATURAL",
        "key": "afs:sort=versionFacet",
        "order": "DESC"
      }
    ],
    "periodFilter": {
      "periodType": "CUSTOM",
      "period": {
        "from": "2022-07-08",
        "to": "2023-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.
`sort`	Array	Indicates if search results are sorted based on certain criteria.
`type`	String	The sorting method to be applied to search results. Possible values are `ALPHA` and `NATURAL`.
`key`	String	A parameter prefixed by `afs:sort` that defines additional criteria by which to sort search results.
`order`	Boolean	Defines the sort order. Possible values are `ASC` and `DESC`.
`periodFilter`	Object	Filters search results by period.
`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.

Update a search - Fluid Topics - Latest

Fluid Topics API Reference Guide