Semantic search - Fluid Topics

This web service allows users to search in Fluid Topics using natural language (full questions) instead of keywords. This search method uses semantic similarity rather than keyword match.

This web service is in beta. It is likely to evolve.

Semantic search is a premium feature that requires a subscription. Please get in touch with a Fluid Topics representative for more information.

Method	Endpoint
`POST`	`/api/beta/khub/topics/semantic-search`

Request example

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

{
  "query": "With what user role can I create a content package?",
  "contentLocale": "en-US",
  "filters": [
    {
      "key": "Category",
      "values": ["Reference Guide", "Technical Notes"]
    }
  ],
  "nbResults": 2
}

Field	Type	Required?	Description
`query`	String	Yes	Expects the string query used to return matching publications.
`contentLocale`	String	Yes	Expects the desired content language's ISO code.
`filters`	Array	No	Filters the results based on selected criteria.
`key`	String	No	Expects a metadata key.
`values`	Array	No	Defines the values for the selected key.
`nbResults`	Integer	No	The number of results for the query. Should be between `1` and `20`. Defaults to `5`.

Response body

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

{
    "query": {
        "date": "2023-11-27T10:10:01.567426+00:00",
        "parameters": {
            "filters": [
                {
                    "key": "Category",
                    "values": [
                        "Technical Notes"
                    ]
                }
            ],
            "query": "With what user role can I create a content package?",
            "top_k": 2
        },
        "version": "0.12.2"
    },
    "results": [
                {
            "map": {
                "excerpt": "the content packager extension lets admin and khub_admin users download bundles of content in HTML format.",
                "map_id": "lGZyb2NkJXllep673jlaew",
                "metadata": {
                    ... List of all key/values metadata and technical facets (not only the configured ones) ...
                },
                "relevance": "0.5761601328849792",
                "title": "Content Packager"
            },
            "type": "MAP"
        },
        {
            "topic": {
                "content_id": "KZqGFvOel3Boeqo0RqY4pw",
                "excerpt": "prerequisites before creating content packages, it is necessary to : - enable collections. since collections are not enabled by default, an admin or portal _ admin user must manually activate the toggle switch in the features toggling administration interface. if collections are not enabled, it will be impossible to create content packages. - create an api key in the api key administration interface, available for admin users. it should have the name \" content - packager \" and the following roles : - khub _ admin to access any required document on the fluid topics portal - users _ admin to access collections",
                "map_id": "T5a4pP8KerYCojPZJbJt6Q",
                "map_title": "Content packager",
                "metadata": {
                    ... List of all key/values metadata and technical facets (not only the configured ones) ...
                },
                "relevance": "0.5025011301040649",
                "title": "Prerequisites",
                "toc_id": "yCrZv2ggt3IneEqAXlSL~A"
            },
            "type": "TOPIC"
        }
    ]
}

Field	Type	Description
`query`	Object	An object containing the information of the request body.
`date`	String	The date and time of the request. Date is in `YYYY-MM-DD` format, and time is in 24-hour format, GMT.
`parameters`	Object	Parameters set for the search in the request body.
`filters`	Array	Filters set for the search in the request body.
`key`	String	Metadata key set for the search in the request body.
`values`	Array	Metadata key values set for the search in the request body.
`query`	String	The string query used to return matching publications.
`top_k`	Number	The number of results set for the search in the request body.
`version`	String	The web service version.
`results`	Array	An array containing all search results, sorted by descending relevance score.
`topic`	Object	An object containing information about a search result that is a topic.
`map`	Object	An object containing information about a search result that is a map.
`content_id`	String	Corresponds to the Content ID of the topic. Not available when the parent object is a `map`.
`excerpt`	String	The text found as relevant for the given query.
`map_id`	String	Corresponds to the value of the `khubId` of the topic.
`map_title`	String	Corresponds to the value of the `ft:title` metadata key for the map. Not available when the parent object is a `map`.
`metadata`	Object	An object containing the metadata for the topic.
`relevance`	String	A relevance score from `0` to `1`. `0` is the lowest possible score, while `1` is the highest possible score.
`title`	String	Corresponds to the value of the `ft:title` metadata key for the topic.
`toc_id`	String	Corresponds to the value of the ToC ID of the topic. Not available when the parent object is a `map`.
`type`	String	The document type, can be `TOPIC` or `MAP`.

Return code	Description
`200 OK`	The web service returns search results.

For a comprehensive list of all possible return codes, see Return codes.

Semantic search - Fluid Topics - Latest

Fluid Topics API Reference Guide