Search documents - Fluid Topics

This web service lets users search unstructured documents. It returns unclustered documents matching the query conditions through a paginated response.

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/documents/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 document's `ft:lastTechChange` metadata. 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.

It is possible to use pagination with this web service.
- Using pagination when searching documents 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.

Request body

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

The word "training" is deliberately misspelled as "trainin" as the value for the query field.

{
  "query": "trainin",
  "contentLocale": "en-US",
  "facets": [
    {
      "id": "FileType",
      "maxDepth": 1
    }
  ],
  "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"
    }
  ],
  "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, an empty search is queried.
`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, Fluid Topics replaces `fr` 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.
`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	Specifies a custom sort on any metadata.
`key`	String	Yes	Sort criterion keys can be any user metadata or technical facets, such as `ft:lastPublication`, `ft:topicTitle`. `ft:relevance` is a special keyword provided to sort by relevance.
`order`	String	Yes	Each criterion can be ascending (`ASC`) or descending (`DESC`). By default, the standard Fluid Topics sort order is used.
`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 in 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 documents in alphabetical order.

Response body

{
  "spellcheck": {
    "suggestedQuery": "Training",
    "htmlSuggestedQuery": "<span class=\"kwicmatch\">Training</span>"
  },
  "facets": [
    {
      "key": "FileType",
      "label": "FileType",
      "hierarchical": false,
      "multiSelectionable": false,
      "rootNodes": [
        {
          "value": "HTML",
          "label": "HTML",
          "selected": false,
          "totalResultsCount": 4,
          "childNodes": [],
          "descendantSelected": false
        },
        {
          "value": "PDF",
          "label": "PDF",
          "selected": false,
          "totalResultsCount": 7,
          "childNodes": [],
          "descendantSelected": false
        }
      ]
    }
  ],
  "results": [
    {
      "documentId": "wuq~8lXw7YHaFWfTkn~CFA",
      "title": "Fluid Topics Training Catalog",
      "htmlTitle": "<span class=\"kwicstring\">Fluid Topics </span><span class=\"kwicmatch\">Training</span><span class=\"kwicstring\"> Catalog</span>",
      "htmlExcerpt": "<span class=\"kwicstring\">FluidTopicsTrainingCatalog2024 </span><span class=\"kwicmatch\">Training</span><span class=\"kwictruncate\">...</span><span class=\"kwicstring\">. Each </span><span class=\"kwicmatch\">training</span><span class=\"kwicstring\"> session is designed</span><span class=\"kwictruncate\">...</span><span class=\"kwicstring\">to our core </span><span class=\"kwicmatch\">training</span><span class=\"kwicstring\"> curriculum, we also propose specific and on-site </span><span class=\"kwicmatch\">training</span><span class=\"kwicstring\">. Contact your Fluid Topics sales representative to choose the right </span><span class=\"kwicmatch\">training</span><span class=\"kwicstring\"> path based on your</span><span class=\"kwictruncate\">...</span><span class=\"kwicstring\">provided during the </span><span class=\"kwicmatch\">training</span><span class=\"kwicstring\">) Duration 2 days</span><span class=\"kwictruncate\">...</span>",
      "filename": "FluidTopicsTrainingCatalog2024.pdf",
      "mimeType": "application/pdf",
      "metadata": [
        {
          "key": "category",
          "label": "Category",
          "values": [
            "Reference Guides"
          ]
        },
        {
          "key": "version",
          "label": "Version",
          "values": [
            "1.0"
          ]
        }
      ],
      "source": {
        "id": "source_42",
        "name": "My_source",
        "type": "UnstructuredDocuments",
        "description": "This is the source through which I retrieve content"
      },
      "lastEditionDate": "2024-04-09",
      "lastPublicationDate": "2024-04-0èT12:45:30.869549",
      "openMode": "FLUIDTOPICS",
      "originUrl": "http://origin-url/...",
      "documentUrl": "https://my_site.fluidtopics.net/khub/documents/wuq~8lXw7YHaFWfTkn~CFA/topics/gsHgq~embEA~MlOr7OK3mA",
      "contentUrl": "https://my_site.fluidtopics.net/khub/documents/wuq~8lXw7YHaFWfTkn~CFA/content",
      "viewerUrl": "http://my_site.fluidtopics.net/v/u/Fluid-Topics-Training-Catalog"
    }
  ],
  "paging": {
    "currentPage": 1,
    "totalResultsCount": 1,
    "isLastPage": true
  }
}

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 documents - Fluid Topics - Latest

Fluid Topics API Reference Guide