Introduction to Cludo API: Setup, Search, and Indexing

17 Jun, 2025 Analytics, Configuration, How To, Implementation


Cludo’s API implementation offers a flexible and customizable approach to integrating advanced search functionalities into your website or application. This guide provides a detailed overview of setting up Cludo’s API on the customer side.

How do Cludo’s APIs work?

Cludo offers a powerful set of APIs designed to give you full flexibility in integrating and managing your search experience. Whether you’re building a custom frontend search interface or managing content behind the scenes, our APIs provide the tools you need.

→ Go to API Documentation

Building Search Experiences

To set up and customize the search functionality on your website or application, you will use Cludo’s search engine endpoints. This includes capabilities such as performing search queries, applying filters, handling pagination, and more.

These features are supported through Version 3 of the API, which provides all the necessary endpoints for retrieving and displaying search results. Version 3 is recommended if you are developing a custom search interface using a frontend framework or if you want full control over the design and behavior of the search experience.

Managing Search Content

To control what content is indexed and how it appears in search results, Cludo provides two key APIs under Version 4 (V4):

  • Crawler API: Trigger on-demand crawls of specific URLs to ensure timely updates, which are ideal for news, events, or product launches that need fast indexing.
  • Index API: Push structured content directly into your search index. Define titles, descriptions, URLs, and custom metadata for full control over content representation.

Prerequisites

Before initiating the API integration, ensure you have the following:

  • Customer ID and Engine ID: these identifiers are essential for API requests. You can find them in MyCludo under Configuration > API. 
  • API Key or Site Key: used for authenticating your requests.
  • API Hostname: corresponds to your account’s region (e.g., api-us1.cludo.com). This information is also available in the API in MyCludo.

Authentication Methods

Cludo supports two primary authentication methods:

1. Site Key Authentication

Designed for public-facing search functionalities, this method prevents the exposure of your API key. The credentials must be Base64-encoded in the following format:

Authorization: SiteKey <Base64-encoded string>

Where the Base64-encoded string represents:

<Customer ID>:<Engine ID>:SearchKey

This method is suitable when you want to embed search functionalities directly into your website without compromising security. 

2. Basic Authentication

Utilized for administrative tasks such as managing content or accessing analytics. This method requires your customer ID as the username and the API key as the password. This is typically used in server-to-server communications where the API key can be securely stored.

Setting Up Search Functionality

To implement search using Cludo’s API:

  1. Construct Search Requests: use the appropriate endpoint (e.g., /api/v4/search) with necessary parameters such as query terms, filters, and pagination details.
  2. Handle Search Responses: parse the JOSN or HTML responses to display relevant search results on your website.
  3. Implement Autocomplete: utilize the autocomplete endpoint to provide real-time search suggestions as users type their queries.

Detailed documentation and examples are available in Cludo’s V4 Documentation here.

AI Summary on a custom results page

If you build search with the Cludo API or a custom frontend, you can add AI Summary through Experience Builder on the same page. Your integration keeps calling the Search API and rendering results. Experience Builder renders and manages the summary UI.

Configure AI Summary in Experience Builder the same way as for template implementations. See AI Summary for the Experience Builder checklist.

If CludoJS performs search on the page (for example through Cludo’s React component library), you may only need Experience Builder and the Experience Manager script. If your backend or frontend calls the Search API and renders results itself, you also need CludoJS on the page and must pass each response to CludoJS as described below.

What you need on the page

  • CludoJS (search-script.min.js) with clientTemplates: true in your Cludo configuration.
  • The Experience Manager script on the same page. See Experience Builder.
  • A call to searchResultTemplateClient after each Search API response you render (see below).

Pass search results to CludoJS

After your Search API call returns, pass the JSON response to your Cludo instance:

const inst = window.CludoSearchInstances?.[0]; // or your Cludo instance reference

if (inst) {
  inst.params.query = searchQuery;   // set when the API response does not echo the query
  inst.params.page = pageNumber;     // set on each search; see pagination note below
  inst.searchResultTemplateClient(searchResponse, null);
}

searchResultTemplateClient is the standard hook when you inject API results into CludoJS. It updates Cludo search state, supports analytics, and signals that a first-page search has completed so Experience Builder can request a summary.

If you render results on the server, run this from client-side JavaScript after the page loads, using the same response that built the HTML. If you fetch in the browser, call it in your search success handler.

You do not need to call the summarize endpoints yourself when Experience Builder handles the summary UI. You also do not need to dispatch browser events manually when you use searchResultTemplateClient with a current search-script.min.js bundle from customer.cludo.com.

Pagination

Set inst.params.page before each searchResultTemplateClient call. CludoJS triggers AI Summary only on the first page of results (page 1 or 0). If params.page stays at 1 while the user paginates, the summary can regenerate on every page.

Search response requirements

The search response should include QueryId, TypedDocuments, and GenerativeAnswerAvailable: true when a summary should be offered for that query.

The Search API sets GenerativeAnswerAvailable when AI Summary is enabled for your account, the engine is eligible, the query returns at least one result, and the query meets summary criteria. That can include, among other things:

  • A matching Page Ranking for the query.
  • At least one highlighted title in the top results (often from sending highlight: true on the search request).
  • Hybrid search (AI Search) enabled on the engine.
  • A matching AI Canned Response.

If GenerativeAnswerAvailable is false, your results still display, but Experience Builder does not request a summary. That is expected for some queries.

Troubleshooting

Results show, but AI Summary stays empty: confirm the Experience Builder experience is published, visible, and the Display URL matches the page. Confirm both CludoJS and the Experience Manager script load without errors. Confirm you call searchResultTemplateClient after a first-page search, with clientTemplates: true in your Cludo config. In the browser network tab, check for POST .../search/summarize/stream after that search. If the call never runs, the page is not wired correctly. If it runs but fails, check the response status and that GenerativeAnswerAvailable was true in the search response. Confirm inst.params.query is set when the API response omits the query text.

Console error “Method is not supported”: searchResultTemplateClient requires clientTemplates: true in your Cludo configuration.

Summary appears on every page of results: update inst.params.page before each searchResultTemplateClient call so CludoJS can tell when you are paginating.

For a fully custom summary UI instead of Experience Builder, see the AI Summary API reference.

Implementing Analytics Tracking

To monitor and analyze search behavior, you can use one of the following methods:

  • Include Cludo’s API Analytics Script Add the provided JavaScript snippet to your search results page. Learn more in this article.
  • Configure Data Attributes Ensure your HTML elements include the necessary data attributes for tracking queries and clicks.
    • You can also use the query and clicklog endpoints to track user search queries and interactions programmatically.
Tags:  

Related Posts