Create a search - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

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.

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", 
    "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"
      }
    }
  }
}
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.
    filters Array No The filters applied to the search query.
        key String Yes The filter's metadata key.
        values String 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 Array 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.
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",
        "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"
      }
    }
  },
  "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.