AI Integration Guide

Add AI-powered answers and summaries to your search experience.

Cludo offers multiple AI features that enhance search results by generating answers:

• AI Chat: Users ask natural language questions and receive conversational answers with citations
• AI Summary: Summarize a set of search results into a concise overview
• AI Mode: A conversational follow-up flow that starts from an AI Summary and continues with AI Chat on the same thread

Prerequisites

• AI Search enabled on your Cludo engine
• SiteKey or API Key credentials

---

AI Chat

AI Chat generates conversational answers grounded in your indexed content. Users ask a question, and the AI returns an answer with citations to source pages.

For streaming AI Chat, citations are included inline in the streamed text by default. Setting includeCitations does not change the streaming response.

Basic request

EU

curl -X POST "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer" \
  -H "Authorization: SiteKey {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I install the search widget?",
    "includeCitations": true
  }'

Multi-turn conversations

Pass the conversationId from a previous response to continue the conversation:

{
  "question": "Can you give me more details?",
  "conversationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

For independent questions, omit conversationId to start fresh.

Answer length

Control verbosity with the answerLength parameter:

Value	Description
"comprehensive"	Full, detailed answer (default)
"concise"	Brief, to-the-point answer

See the AI Chat API reference for all parameters.

---

AI Summary

AI Summary synthesizes multiple search results into a single overview. Unlike AI Chat, you first run a search, then pass selected results to the summary endpoint.

Workflow

Step 1: Run a search to get results and a queryId:

curl -X POST "https://api.cludo.com/api/v4/{customerId}/{engineId}/search" \
  -H "Authorization: SiteKey {token}" \
  -H "Content-Type: application/json" \
  -d '{"query": "getting started", "perPage": 5}'

Step 2: Pass selected results to the summary endpoint:

Send no more than 5 sources. For each source, prefer the Title and Content fields when they are available.

EU

curl -X POST "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/summarize" \
  -H "Authorization: SiteKey {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "getting started",
    "queryId": "abc123...",
    "sources": [
      {"resultIndex": 1, "id": "https://example.com/page1", "fields": ["Title", "Content"]},
      {"resultIndex": 2, "id": "https://example.com/page2", "fields": ["Title", "Content"]}
    ],
    "includeCitations": true
  }'

See the AI Summary API reference for all parameters.

---

AI Mode

AI Mode is a conversational follow-up pattern: the first answer is grounded in your search results, and every follow-up keeps the same thread. From the user’s perspective it’s typically an “Ask AI” button that opens a chat panel on the search page.

It does not have its own endpoint. AI Mode uses AI Summary for the first turn and AI Chat for every follow-up, threaded together on a single conversation id.

Workflow

AI Mode uses the streaming variants of both endpoints so the answers render progressively in the chat UI.

Step 1: Run a search to get a QueryId and the top results, exactly as in AI Summary, Step 1.

Step 2: Send the user’s first question to the streaming AI Summary endpoint /search/summarize/stream with up to 5 source documents from Step 1 — same request body as in AI Summary, Step 2. Read the summaryRequestId from the Cludo-Summary-Request-Id response header — you’ll use it as the conversation id for every follow-up.

Step 3: Send every follow-up to the streaming AI Chat endpoint /search/answer/stream, passing the summaryRequestId from Step 2 as conversationId. Reuse the same conversationId for every subsequent follow-up so the AI keeps context.

EU

curl -X POST "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer/stream" \
  -H "Authorization: SiteKey {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Can you give me more details on the installation step?",
    "conversationId": "{summaryRequestId from Step 2}"
  }'

Continuing from an AI Summary on the search page

If you already render an AI Summary above your search results, you can let users click a button on that summary to keep asking questions — without running a second summarize call.

The shortcut: reuse the summaryRequestId you already received from the SERP’s AI Summary as the conversationId on the first /search/answer/stream request. Display the existing summary as the first turn of the conversation client-side, then continue with the streaming AI Chat endpoint for every follow-up.

{
  "question": "What about for the US data center?",
  "conversationId": "{summaryRequestId already shown on the search page}"
}

See the AI Summary API reference and AI Chat API reference for all parameters.

---

Collecting Feedback

Track user feedback to improve AI quality. Both AI Chat and AI Summary have feedback endpoints:

const BASE_URL = "https://api.cludo.com"; // Use https://api-us1.cludo.com for US

// AI Chat feedback
async function submitChatFeedback(conversationId, exchangeId, rating) {
  await fetch(
    `${BASE_URL}/api/v4/${customerId}/${engineId}/search/answer/feedback`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ conversationId, exchangeId, rating })
    }
  );
}

// AI Summary feedback
async function submitSummaryFeedback(summaryId, rating) {
  await fetch(
    `${BASE_URL}/api/v4/${customerId}/${engineId}/search/summarize/feedback`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ summaryId, rating })
    }
  );
}

---

When to Use Which

Use Case	Feature
User asks a direct question	AI Chat
Show a summary above search results	AI Summary
Conversational follow-up questions	AI Chat
Synthesize specific documents	AI Summary
Follow-up questions on a summarized search	AI Mode