Search topics - Fluid Topics

This web service searches a topic's title, content, and metadata. It returns topics matching the query conditions through a paginated response body.

The spellcheck option is active by default. If the query contains a misspelling, the request is launched again with the new spelling suggested by the spellchecker.

Users can add facets to filter the matching publications.

Method	Endpoint
`POST`	`/api/khub/topics/search`

Query string parameter	Type	Required?	Description
`page`	Number	No	Expects the page number. Starts at `1`.
`per_page`	Number	No	Expects the number of results per page. Starts at `1`. The maximum accepted value is `500`.
`from`	String	No	The inclusive start date of the period on which to filter results based on the value of a topic's `ft:lastTechChange` metadata. If unspecified, the default value is `1970-01-01`.
`to`	String	No	The inclusive end date of the period. The inclusive start date of the period. If unspecified, the default value is the current day.

It is possible to use pagination with this web service.
- Using pagination when searching topics is recommended. Pagination applies by default (default values available in the request example table).
- It is possible to specify a period or paging for this web service using either query parameters or fields in the request body. When using both methods, the values of the query parameters take precedence.
When the HTTP header does not include user credentials, this web service only returns public results.

As a USER_ADMIN user, it is possible to impersonate another user when using this web service.

This web service requires authentication on portals with mandatory authentication.

Return code	Description
`200 OK`	Returns 0 or more results.
`400 BAD REQUEST`	Invalid JSON request body.
`404 NOT FOUND`	No topic matches the filters configured in the path parameters.

Request body

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

The word "metadata" is deliberately misspelled as "metadatq" as the value for the query field.

{
  "query": "metadatq",
  "contentLocale": "en-US",
  "metadataFilters": [
    {
      "key": "version",
      "valueFilter": {
        "values": [
          "1.1",
          "1.2"
        ],
        "negative": false
      }
    },
    {
      "key": "category",
      "valueFilter": {
        "values": [
          "Reference Guides"
        ],
        "negative": false
      }
    }
  ],
  "sort": [
    {
      "key": "ft:lastPublication",
      "order": "DESC"
    }
  ],
  "facets": [
    {
      "id": "author",
      "maxDepth": 1
    }
  ],
  "lastModified": {
    "from": "2024-01-01",
    "to": "2024-04-09"
  },
  "paging": {
    "page": 1,
    "perPage": 20
  }
}

The JSON request body expects the following fields:

Field	Type	Required?	Description
`query`	String	No	Expects the string query used to return matching publications. If not set, other parameters determine the results, such as `contentLocale` and `metadataFilters`.
`contentLocale`	String	No	Expects the content language ISO codes (language and country). If not set, the query fails. If set with an unknown value, Fluid Topics attempts to correct the value. For example, `fr` becomes `fr-FR`.
`uiLocale`	String	No	Expects the UI language ISO code. If not set, Fluid Topics tries to detect the user locale. This locale is used to return facet labels in the correct language, for instance.
`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	Enables specifying a custom sort on any metadata.
`key`	String	Yes	Sort criterion keys can be any user metadata or technical facets. Examples include `ft:lastPublication`, `ft:topicTitle`, and `ft:relevance` (a special keyword provided to sort by relevance).
`order`	String	Yes	Each criterion can be ascending (`ASC`) or descending (`DESC`). By default, uses the standard Fluid Topics sort order.
`facets`	Array	No	Displays facets from their facet ID. Users can filter content through these facets.
`id`	String	Yes	The facet's unique identifier.
`maxDepth`	Number	No	Defines the maximum depth level for the facet. Defaults to `8` if not specified.
`lastModified`	Object	No	Restricts results to those with a value for the `ft:lastTechChange` metadata that is within the specified period.
`from`	String	No	The inclusive start date of the period. If unspecified, the default value is `1970-01-01`.
`to`	String	No	The inclusive end date of the period. If unspecified, the default value is the current day.
`paging`	Object	No	Contains information about pagination settings.
`page`	Number	Yes	The number of the queried result page. Defaults to page 1 if unspecified.
`perPage`	Number	No	The number of result clusters for each page. Defaults to 20 results per page if unspecified.

The request body can be empty ({}), which returns topics in alphabetical order.

Response body

{
  "spellcheck": {
    "suggestedQuery": "metadata",
    "htmlSuggestedQuery": "<span class=\"kwicmatch\">metadata</span>"
  },
  "facets": [
    {
      "key": "ft:isPublication",
      "label": "ft:isPublication",
      "hierarchical": false,
      "multiSelectionable": true,
      "rootNodes": [
        {
          "value": "John Doe",
          "label": "John Doe",
          "selected": false,
          "totalResultsCount": 19,
          "childNodes": [],
          "descendantSelected": false
        },
        {
          "value": "Paul Dupont",
          "label": "Paul Dupont",
          "selected": false,
          "totalResultsCount": 8,
          "childNodes": [],
          "descendantSelected": false
        }
      ]
    }
  ],
  "results": [
    {
      "mapId": "qT_JLCMeNICKqt7tLEWRdg",
      "mapTitle": "Integrate the Fluid Topics API",
      "occurrences": [
        {
          "tocId": "P4gRbk8npq~xsOfvIMH6Vg",
          "readerUrl": "http://my_site.fluidtopics.net/r/Integrate-the-Fluid-Topics-API/Events/Analytics-events/Topic-events/topic.unrate",
          "breadcrumb": [
            "Events",
            "Analytics events",
            "Topic events",
            "topic.unrate"
          ]
        }
      ],
      "contentId": "yYqIvTEE47_eIK4MGSfoKQ",
      "topicUrl": "http://my_site.fluidtopics.net/api/khub/maps/2qCoH7U~z73O75bH4NoYbw/topics/yYqIvTEE47_eIK4MGSfoKQ",
      "contentUrl": "http://my_site.fluidtopics.net/api/khub/maps/2qCoH7U~z73O75bH4NoYbw/topics/yYqIvTEE47_eIK4MGSfoKQ/content",
      "htmlTitle": "<span class=\"kwicstring\">topic.unrate</span>",
      "htmlExcerpt": "<span class=\"kwictruncate\">...</span><span class=\"kwicstring\">contains its tocId and title . document An object containing information about the document.      id The document&#x27;s identifier.      </span><span class=\"kwicmatch\">metadata</span><span class=\"kwicstring\"> A list of the document&#x27;s </span><span class=\"kwicmatch\">metadata</span><span class=\"kwicstring\"> with the label and values of each key.      title The title of the document.      type The document&#x27;s type (</span><span class=\"kwictruncate\">...</span>",
      "metadata": [
        {
          "key": "category",
          "label": "Category",
          "values": [
            "Reference Guides"
          ]
        },
        {
          "key": "version",
          "label": "Version",
          "values": [
            "1.0"
          ]
        }
      ],
      "resources": [
        {
          "id": "I0uufqIcCMdfLNXUGSTDYw",
          "filename": "update_mode.png",
          "mimeType": "image/png",
          "viewerUrl": "http://my_site.fluidtopics.net/viewer/attachment/ENQRHyDq~oYAqQn5tJAjKA/I0uufqIcCMdfLNXUGSTDYw",
          "resourceUrl": "http://my_site.fluidtopics.net/api/khub/maps/ENQRHyDq~oYAqQn5tJAjKA/resources/I0uufqIcCMdfLNXUGSTDYw",
          "resourceContentUrl": "http://my_site.fluidtopics.net/api/khub/maps/ENQRHyDq~oYAqQn5tJAjKA/resources/I0uufqIcCMdfLNXUGSTDYw/content"
        }
      ]
    }
  ],
  "paging": {
    "currentPage": 1,
    "lastPage": false,
    "totalResultsCount": 850
  }
}

Where:

kwicstring is the part of the original query which was correctly spelled.
kwicmatch is the part of the query corrected by the spellchecker.

Search topics - Fluid Topics - Latest

Fluid Topics API Reference Guide