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 activated by default. If the query is misspelled, the request is launched again with the new spelling suggested by the spellchecker.

Facets can be added for users 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` and defaults to `1`.
`per_page`	Number	No	Expects the number of results per page. Defaults at `-1`, meaning that all results are returned. 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.
It is possible to specify a period for this web service using either query parameters or fields in the request body. If both methods are used, the values of the query parameters take precedence.

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

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

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",
  "filters": [
    {
      "key": "version",
      "values": ["1.1", "1.2"]
    },
    {
      "key": "category",
      "values": ["Reference Guides"]
    }
  ],
  "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, the results are based on other parameters, such as `contentLocale` and `filters`.
`contentLocale`	String	Yes	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` is replaced by `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.
`filters`	Array	No	Filters the results on some metadata values. The filter object expects the following criteria: `key` (mandatory): Filter keys can be any user metadata or technical facets. `values` (mandatory): Defines the value for the given `key`. When multiple values are given, they are combined with an AND or an OR operator depending on the tenant configuration. `negative` (optional): When set to `true`, the results matching the previously set `values` are excluded. By default, the `negative` parameter is implicit and set to `false`. Defaults to empty list.
`sort`	Array	No	Enables to specify a custom sort on any metadata. The sort object expects the following criteria: `key` (mandatory): Sort criterion keys can be any user metadata or technical facets, for example: `ft:lastPublication` `ft:topicTitle` `ft:relevance` is a special keyword is provided to sort by relevance. `order` (mandatory): Each criterion can be ascendant (`ASC`) or descendant (`DESC`). By default, the standard Fluid Topics sort order is used.
`facets`	Array	No	Displays facets from their facet ID. Users can then filter content through these facets. Facets are displayed in the same order as they are declared. If `facets` is absent or present but empty, no facet is displayed. The facet object expects the following criteria: `id` (mandatory): Is the facet ID. `maxDepth` (optional): Defines the maximum depth level for the facet. When displaying a hierarchical facet, by default, the whole hierarchy is displayed.
`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	Expects the following paging information: `page` (mandatory): Is the number of the queried result page. `perPage` (optional): Is the number of result clusters for each page. By default, the pagination is set to page 1 and 20 results per page.

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