> ## 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 Chat
> Returns a generative answer for the given question, with optional citations and multi-turn conversation support. For streaming AI Chat, citations are included inline in the streamed text by default, so `includeCitations` does not change the streamed output.
You are viewing the **standard** endpoint which returns a complete JSON response.
The streaming endpoint is the same path as standard with `/stream` appended:
`POST /api/v4/{customerId}/{engineId}/search/answer/stream`.
It accepts the same request body as the standard endpoint, but streams the response as plain text chunks.
Citations are included inline in the streamed text by default, so `includeCitations` does not change the streaming response.
Response headers include `Cludo-Conversation-Id` and `Cludo-Exchange-Id` for conversation tracking.
***
## Multi-turn conversations
Pass the `conversationId` from a previous response to continue the conversation. For independent questions, omit `conversationId` to start fresh.
***
## OpenAPI
````yaml POST /api/v4/{customerId}/{engineId}/search/answer
openapi: 3.1.0
info:
title: Cludo AI API
version: 4.0.0
description: >-
AI Chat, streaming answers, feedback and click tracking, and AI Summary
endpoints for Cludo search engines.
servers:
- url: https://api.cludo.com
description: EU region (Customer IDs below 10,000,000)
- url: https://api-us1.cludo.com
description: US region (Customer IDs 10,000,000 and above)
security:
- SiteKey: []
paths:
/api/v4/{customerId}/{engineId}/search/answer:
post:
summary: AI Chat
description: >-
Returns a generative answer for the given question, with optional
citations and multi-turn conversation support. For streaming AI Chat,
citations are included inline in the streamed text by default, so
`includeCitations` does not change the streamed output.
operationId: getAiAnswer
parameters:
- $ref: '#/components/parameters/customerId'
- $ref: '#/components/parameters/engineId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AiChatRequest'
responses:
'200':
description: Successful AI Chat response.
content:
application/json:
schema:
$ref: '#/components/schemas/AiAnswerResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- SiteKey: []
- BasicAuth: []
components:
parameters:
customerId:
name: customerId
in: path
required: true
description: Your Cludo account ID.
schema:
type: integer
engineId:
name: engineId
in: path
required: true
description: Search engine ID.
schema:
type: integer
schemas:
AiChatRequest:
type: object
required:
- question
properties:
question:
type: string
description: >-
End-user question in natural language. Grounding content is
retrieved from your indexed pages.
conversationId:
type: string
format: uuid
description: >-
Reuse the **same** id from a previous AI Chat response to continue a
thread; omit or use a new id to start fresh (streaming responses
expose ids in headers too).
language:
type: string
description: >-
ISO-639-1 or simple locale code for answer language (e.g. `en`,
`da`).
answerLength:
type: string
enum:
- comprehensive
- concise
description: >-
`comprehensive` for longer explanations; `concise` for short
answers.
customPrompt:
type: string
description: >-
Extra system-style instructions (tone, disclaimers, formatting). Use
sparingly; overrides can affect safety and quality.
includeCitations:
type: boolean
description: >-
For non-streaming AI Chat, when **true**, the JSON response includes
`citations` with title, url, and snippet for each source used. For
streaming AI Chat, citations are included inline in the streamed
text by default and this flag does not change the streamed output.
Server default: `False`.
AiAnswerResponse:
type: object
properties:
value:
$ref: '#/components/schemas/AiAnswerValue'
AiAnswerValue:
type: object
properties:
answer:
type: string
description: Final natural-language reply to show the user.
url:
type: string
description: >-
Optional primary link when the answer maps cleanly to one
destination.
chatSessionId:
type: string
description: >-
Server-side session id (may align with `conversationId` depending on
deployment).
conversationId:
type: string
description: >-
Pass this on the next `AiChatRequest` to continue the same
conversation.
exchangeId:
type: string
description: >-
Identifies this specific Q/A pair. Use with feedback and click
endpoints.
citations:
type: array
description: >-
Populated in non-streaming AI Chat responses when `includeCitations`
was true in the request.
items:
$ref: '#/components/schemas/AiCitation'
couldAnswer:
type: boolean
description: >-
Whether the AI was able to generate a meaningful answer from the
indexed content.
ErrorResponse:
type: object
description: Error response returned when a request fails.
properties:
message:
type: string
description: A message describing what went wrong.
UnauthorizedError:
type: object
description: Returned when authentication fails.
properties:
message:
type: string
description: Authentication failure reason.
ServerError:
type: object
description: Returned when an unexpected server error occurs.
properties:
status:
type: string
description: HTTP status name.
code:
type: integer
description: HTTP status code.
messages:
type: array
items:
type: string
description: Error details, usually including a support reference id.
AiCitation:
type: object
properties:
reference:
type: integer
description: Citation number matching `[n]` in the answer text.
url:
type: string
description: Source page URL.
pageTitle:
type: string
description: Title of the source page.
responses:
BadRequest:
description: >-
The request is invalid. This typically occurs due to missing required
fields, incorrect parameter values, or malformed request body.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
message: >-
The request could not be processed. Check the request body and
required parameters.
Unauthorized:
description: >-
Authentication failed. The Authorization header is missing or contains
invalid credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/UnauthorizedError'
example:
message: unauthorized
InternalServerError:
description: >-
An unexpected server error occurred. If this persists, contact
support@cludo.com.
content:
application/json:
schema:
$ref: '#/components/schemas/ServerError'
example:
status: InternalServerError
code: 500
messages:
- >-
Error occur. Please contact support with error ID:
a1b2c3d4-e5f6-7890-abcd-ef1234567890
securitySchemes:
SiteKey:
type: apiKey
in: header
name: Authorization
description: >-
SiteKey authentication. Pass the full value including the `SiteKey`
prefix: `SiteKey `. Example:
`SiteKey dGVzdDoxMjM0NTY3Ojk4NzY1`.
BasicAuth:
type: http
scheme: basic
description: >-
Basic authentication. Use your Customer ID as the username and API Key
as the password. Example header: `Authorization: Basic
MTIzNDU2NzpteS1hcGkta2V5`.
````