> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cludo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Integration Guide

> Step-by-step guide to integrating Cludo AI Chat and AI Summary endpoints, including streaming responses, citations, and multi-turn conversations.

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

```bash EU theme={null}
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
  }'
```

```bash US theme={null}
curl -X POST "https://api-us1.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:

```json theme={null}
{
  "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](https://docs.cludo.com/api-reference/v4/ai/chat.md) 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`:

```bash theme={null}
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.

```bash EU theme={null}
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": [
      {"id": "https://example.com/page1", "fields": ["Title", "Content"]},
      {"id": "https://example.com/page2", "fields": ["Title", "Content"]}
    ],
    "includeCitations": true
  }'
```

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

> [!NOTE]
>
> `includeCitations` applies only to the streaming endpoint (`/search/summarize/stream`) and has no effect on this standard summary response. Likewise, `answerLength` and `customPrompt` are in limited availability and only change the output for accounts where those features have been enabled — contact your account manager (with your customer ID and engine ID) to discuss enabling them.

See the [AI Summary API reference](https://docs.cludo.com/api-reference/v4/ai/summary.md) 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](#ai-summary).

**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](#ai-summary). Read the `summaryId` from the `Cludo-Summary-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 `summaryId` from Step 2 as `conversationId`. Reuse the same `conversationId` for every subsequent follow-up so the AI keeps context.

```bash EU theme={null}
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": "{summaryId from Step 2}",
    "tags": ["ai_mode"]
  }'
```

```bash US theme={null}
curl -X POST "https://api-us1.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}",
    "tags": ["ai_mode"]
  }'
```

### 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 `summaryId` 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.

```json theme={null}
{
  "question": "What about for the US data center?",
  "conversationId": "{summaryId already shown on the search page}",
  "tags": ["ai_mode"]
}
```

### Tagging AI Mode requests

To have your AI Mode counted as AI Mode in analytics, send `"tags": ["ai_mode"]` on the AI Summary request in Step 2 and on every AI Chat follow-up in Step 3, not only the first.

A request counts as AI Mode only when it carries exactly `ai_mode`. Requests without it count as standalone AI Chat or AI Summary. That includes other spellings: tags are sanitized before they are stored, so `ai-mode`, for example, is stored as `aimode`. See the `tags` field in the [AI Chat](https://docs.cludo.com/api-reference/v4/ai/chat.md#tagging-requests-for-analytics) and [AI Summary](https://docs.cludo.com/api-reference/v4/ai/summary.md#tagging-requests-for-analytics) references for the sanitizing rules.

See the [AI Summary API reference](https://docs.cludo.com/api-reference/v4/ai/summary.md) and [AI Chat API reference](https://docs.cludo.com/api-reference/v4/ai/chat.md) for all parameters.

***

## Collecting feedback

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

```javascript theme={null}
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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.