> ## 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

<CodeGroup>
  ```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
    }'
  ```
</CodeGroup>

### 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](/api-reference/v4/ai/chat) 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.

<CodeGroup>
  ```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
    }'
  ```
</CodeGroup>

<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.
</Note>

See the [AI Summary API reference](/api-reference/v4/ai/summary) 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 `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.

<CodeGroup>
  ```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": "{summaryRequestId from Step 2}"
    }'
  ```

  ```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}"
    }'
  ```
</CodeGroup>

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

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

See the [AI Summary API reference](/api-reference/v4/ai/summary) and [AI Chat API reference](/api-reference/v4/ai/chat) for all parameters.

***

## Collecting ffeedback

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 wuse 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    |