Clustered semantic search - Fluid Topics - Latest

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

This web service allows users role to retrieve clustered search results for the semantic search.

  • 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.
Method Endpoint
POST 
/api/khub/semantic/clustered-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

[
  {
    "clusterId": [
      "89c2f3c2379c0b4e25ea89pm5184df3db6e157d30ef0684b2805976158312240-introduction"
    ],
    "documents": [
      {
        "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": [
            "John Doe"
          ],
          "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
clusterId String The clusterId of the documents.
documents Object An object containing the documents for the cluster.
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.