Semantic search - Fluid Topics - Latest

Fluid Topics API Reference Guide
Category
Reference Guides
Audience
public
Version
Latest

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.

  • Semantic search is a premium feature and requires a subscription. Get in touch with a Fluid Topics representative for more information.
  • It is necessary to provide an Ft-Calling-App value when using Fluid Topics web services. See Fluid Topics calling app.

This web service requires authentication on portals with mandatory authentication.

Method Endpoint
POST 
/api/khub/semantic/search

Request example

The following lines show an example of a JSON request body without and / or / not filters:

{
  "query": "What is a drone?",
  "filters": [
    {
      "key": "ft:locale",
      "values": [
        "en-US"
      ],
      "hierarchicalValues": []
    }
  ],
  "nbResults": 5
}

The following lines show an example of a JSON request body with and / or / not filters:

{
  "query": "What is a book?",
  "filters": [
    {
      "and": [
        {
          "not": {
            "key": "ft:isBook",
            "values": [
              "true"
            ]
          }
        },
        {
          "or": [
            {
              "key": "ft:locale",
              "values": [
                "en-US"
              ]
            },
            {
              "key": "ft:locale",
              "values": [
                "en-GB"
              ]
            }
          ]
        }
      ]
    }
  ],
  "nbResults": 5
}

The previous request gets publications that are not books, and that have a ft:locale value of en-US or en-GB.

Field Type Required? Description
query String Yes Expects the string query used to return matching publications.
filters Array No Filters the results based on selected criteria.
and Object No Combines filters requiring all conditions to be met.
or Object No Combines filters requiring any condition to be met.
not Object No Excludes results that match the specified condition.
key String No Expects a metadata key.
values Array No Defines the values for the selected key.
hierarchicalValues Array No Defines hierarchical values for the selected key. It can have an unlimited number of arrays, each representing a hierarchical metadata key. Inside an array, the first string is the value highest in the hierarchy. Each following value is one level down.
nbResults Integer No The number of results for the query. Should be between 1 and 20. Defaults to 5.

For topics belonging to books, the metadata keys and values in the filters field must apply to the topic and not only at the document level. If metadata only applies at the document level, topics are not returned.

Response body

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

[
  {
    "excerpt": "Introduction\n============\n\nWelcome to the Fluid Topics knowledge center.\n\nFluid Topics is a dynamic content delivery platform designed to provide fast and easy access to information.\n\nFluid Topics portals are entirely customizable to better fit a brand's graphic style, and to create the best user experience possible.",
    "relevance": 0.5528038,
    "metadata": {
      "FT_Version": [
        "Latest"
      ],
      "ft:clusterId": [
        "89c2f3c2379c0b4e25ea89pm5184df3db6e157d30ef0684b2805976158312240-introduction"
      ],
      "Category": [
        "Technical Notes"
      ],
      "ft:baseId": [
        "89c2f3c2379c0b4e25ea89pm5184df3db6e157d30ef0684b2805976158312240-introduction"
      ],
      "ft:prettyUrl": [
        "Welcome-to-Fluid-Topics/Introduction"
      ],
      "ft:isBook": [
        "false"
      ],
      "Product": [
        "Fluid Topics"
      ],
      "ft:locale": [
        "en-US"
      ],
      "ft:searchableFromInt": [
        "0"
      ],
      "ft:isPublication": [
        "false"
      ],
      "ft:tocId": [
        "QexhZws3IaEJ0N8fT_raVA"
      ],
      "ft:isArticle": [
        "false"
      ],
      "ft:originId": [
        "89c2f3c2379c0b4e25ea89pm5184df3db6e157d30ef0684b2805976158312240-introduction"
      ],
      "ft:container": [
        "book"
      ],
      "ft:lastTechChange": [
        "2025-04-07"
      ],
      "ft:publicationId": [
        "V9wOYUk2k4XYr8MmDxZjcQ"
      ],
      "ft:lastEdition": [
        "2024-06-18"
      ],
      "ft:publication_title": [
        "Welcome to Fluid Topics"
      ],
      "audience": [
        "public"
      ],
      "ft:isAttachment": [
        "false"
      ],
      "ft:sourceType": [
        "Markdown"
      ],
      "author": [
        "Clément Guillaume"
      ],
      "ft:openMode": [
        "fluidtopics"
      ],
      "media_dir": [
        "images"
      ],
      "Version_FT": [
        "Latest"
      ],
      "ft:khubVersion": [
        "5.0.107"
      ],
      "ft:sourceName": [
        "Markdown Product Knowledge"
      ],
      "ft:isSynchronousAttachment": [
        "false"
      ],
      "ft:rights": [
        "ft:public"
      ],
      "ft:lastTechChangeTimestamp": [
        "1744041907225"
      ],
      "ft:lastPublication": [
        "2024-06-18T15:47:02.935000"
      ],
      "ft:publishUploadId": [
        "Too old to be saved."
      ],
      "ft:isUnstructured": [
        "false"
      ],
      "ft:alertTimestamp": [
        "1718668800"
      ],
      "ft:title": [
        "Introduction"
      ],
      "ft:sourceId": [
        "md"
      ],
      "ft:tocPosition": [
        "1"
      ],
      "ft:publishStatus": [
        "visible"
      ],
      "ft:document_type": [
        "topic"
      ],
      "ft:topicTitle": [
        "Introduction"
      ]
    }
  }
]
Field Type Description
excerpt String The text found as relevant for the given query.
relevance String A relevance score from -1 to 1. -1 is the lowest possible score, while 1 is the highest possible score.
metadata Object An object containing the metadata for the topic.
Return code Description
200 OK The web service returns search results.

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