Search API TruSearch

Search API TruSearch is a Drupal 10.3/11 Search API backend that connects
your site to an external AI-powered hybrid search engine. Search queries are
routed to the TruSearch engine rather than querying a local database. The
engine combines keyword and semantic (vector) search to deliver intelligent,
context-aware results, and can generate AI answers directly from your indexed
content using Retrieval-Augmented Generation (RAG).

All AI, machine learning, and analytics work happens inside the TruSearch
engine. The Drupal module is a thin adapter: it indexes content, proxies
search requests, and renders results. Your Drupal site never calls OpenSearch,
OpenAI, or any third-party AI service directly.

Features

• Hybrid search — Combines keyword (lexical) and semantic
  (vector) search with configurable weighting. Each mode can also be used
  independently.
• AI-generated answers — The engine reads your indexed
  content and generates a direct answer above results (RAG). Users can submit
  helpfulness feedback inline.
• Generative UI widgets — Alongside standard results, the
  engine can return structured cards: step-by-step guides, knowledge cards, and
  ranked lists.
• Autocomplete widget — Embed a pre-built search block
  powered by the engine's JavaScript library. All API communication is proxied
  through Drupal.
• Search overlay — Displays popular and trending queries
  when a user focuses the search field, with configurable quick links.
• Click and conversion tracking — Records which results
  users click and attributes downstream conversions (signups, purchases,
  downloads) back to the originating search.
• Secure widget proxy — Engine panel IDs and API keys
  never reach the browser. A short-lived token is issued per request and
  validated server-side.
• Circuit breaker and fallback — If the engine is
  unavailable, requests fail gracefully with configurable degraded-mode
  behaviour rather than exposing errors to end users.
• No-code search page builder — Design your search
  results page visually in the TruSearch engine dashboard. Bring the Widget ID
  back to Drupal and embed it via a block or a dedicated node type.

Requirements

• Drupal 10.3 or 11
• PHP 8.1+
• Search API
  module
• A running TruSearch engine instance with a valid API key and tenant
  ID

Installation

Install via Composer:

composer require drupal/search_api_trusearch
  drush en search_api_trusearch
  

Configuration

1. Go to Admin → Configuration → Search and metadata → TruSearch
   Settings and enter your engine URL, API key, and tenant ID.
2. Go to Admin → Configuration → Search and metadata → Search
   API and create (or edit) a server using the TruSearch
   backend.
3. Create a Search API index attached to that server and configure which
   content types and fields to index.
4. Run the indexer: drush search-api:index or use the Search
   API UI.
5. Place the widget library files provided by your TruSearch engine
   provider into your theme and register them in
   mytheme.libraries.yml:

   trusearch-widgets:
       js:
         libraries/trusearch/js/trusearch-widgets.iife.js: { minified: true,
     preprocess: false }
       css:
         theme:
           libraries/trusearch/css/trusearch-widgets.css: {}

   Then set Widget vendor library to
   mytheme/trusearch-widgets under TruSearch Settings →
   Advanced.

6. Optionally place the Autocomplete Widget block via the block
   layout UI, or create a TruSearch Page node at
   /admin/content/add/trusearch_page to use as your search results
   page.

The TruSearch engine includes a visual drag-and-drop builder in its
dashboard. You can arrange result cards, facet panels, AI answer boxes,
sorting controls, and pagination without writing any code, then preview the
layout in real time.

Once your layout is ready, the engine gives you a Widget ID. Bring that ID
back to Drupal — you have two options:

• Embed in a page — Create a node of type TruSearch
  Page, enter the Widget ID, and save. The module generates a secure token
  and proxies all widget traffic through Drupal.
• Embed via a block — Place the TruSearch
  Autocomplete Widget block through the standard block layout UI and enter
  the Widget ID in the block settings. The same token-based proxy applies.

When the layout is updated in the engine dashboard, the changes appear on
your site immediately — no redeployment or config changes in Drupal
required.