AI Chat

AI Chat

curl --request POST \
  --url https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "<string>",
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "language": "<string>",
  "customPrompt": "<string>",
  "includeCitations": true,
  "filters": {
    "Category": [
      "Guides"
    ]
  },
  "valueBoost": [
    {
      "fieldName": "<string>",
      "boosts": [
        {
          "boost": 123,
          "values": [
            "<string>"
          ]
        }
      ]
    }
  ],
  "sourceFields": [
    "Title",
    "Content"
  ],
  "tags": [
    "<string>"
  ]
}
'

import requests

url = "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer"

payload = {
    "question": "<string>",
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "language": "<string>",
    "customPrompt": "<string>",
    "includeCitations": True,
    "filters": { "Category": ["Guides"] },
    "valueBoost": [
        {
            "fieldName": "<string>",
            "boosts": [
                {
                    "boost": 123,
                    "values": ["<string>"]
                }
            ]
        }
    ],
    "sourceFields": ["Title", "Content"],
    "tags": ["<string>"]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    conversationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    language: '<string>',
    customPrompt: '<string>',
    includeCitations: true,
    filters: {Category: ['Guides']},
    valueBoost: [{fieldName: '<string>', boosts: [{boost: 123, values: ['<string>']}]}],
    sourceFields: ['Title', 'Content'],
    tags: ['<string>']
  })
};

fetch('https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    conversationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    language: '<string>',
    customPrompt: '<string>',
    includeCitations: true,
    filters: {Category: ['Guides']},
    valueBoost: [{fieldName: '<string>', boosts: [{boost: 123, values: ['<string>']}]}],
    sourceFields: ['Title', 'Content'],
    tags: ['<string>']
  })
};

fetch('https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "value": {
    "answer": "<string>",
    "url": "<string>",
    "chatSessionId": "<string>",
    "conversationId": "<string>",
    "exchangeId": "<string>",
    "citations": [
      {
        "reference": 123,
        "url": "<string>",
        "pageTitle": "<string>"
      }
    ],
    "couldAnswer": true
  }
}

{
  "message": "The request could not be processed. Check the request body and required parameters."
}

{
  "message": "unauthorized"
}

{
  "status": "InternalServerError",
  "code": 500,
  "messages": [
    "Error occur. Please contact support with error ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ]
}

POST

api

{customerId}

{engineId}

answer

AI Chat

curl --request POST \
  --url https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "question": "<string>",
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "language": "<string>",
  "customPrompt": "<string>",
  "includeCitations": true,
  "filters": {
    "Category": [
      "Guides"
    ]
  },
  "valueBoost": [
    {
      "fieldName": "<string>",
      "boosts": [
        {
          "boost": 123,
          "values": [
            "<string>"
          ]
        }
      ]
    }
  ],
  "sourceFields": [
    "Title",
    "Content"
  ],
  "tags": [
    "<string>"
  ]
}
'

import requests

url = "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer"

payload = {
    "question": "<string>",
    "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "language": "<string>",
    "customPrompt": "<string>",
    "includeCitations": True,
    "filters": { "Category": ["Guides"] },
    "valueBoost": [
        {
            "fieldName": "<string>",
            "boosts": [
                {
                    "boost": 123,
                    "values": ["<string>"]
                }
            ]
        }
    ],
    "sourceFields": ["Title", "Content"],
    "tags": ["<string>"]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    conversationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    language: '<string>',
    customPrompt: '<string>',
    includeCitations: true,
    filters: {Category: ['Guides']},
    valueBoost: [{fieldName: '<string>', boosts: [{boost: 123, values: ['<string>']}]}],
    sourceFields: ['Title', 'Content'],
    tags: ['<string>']
  })
};

fetch('https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    question: '<string>',
    conversationId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
    language: '<string>',
    customPrompt: '<string>',
    includeCitations: true,
    filters: {Category: ['Guides']},
    valueBoost: [{fieldName: '<string>', boosts: [{boost: 123, values: ['<string>']}]}],
    sourceFields: ['Title', 'Content'],
    tags: ['<string>']
  })
};

fetch('https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "value": {
    "answer": "<string>",
    "url": "<string>",
    "chatSessionId": "<string>",
    "conversationId": "<string>",
    "exchangeId": "<string>",
    "citations": [
      {
        "reference": 123,
        "url": "<string>",
        "pageTitle": "<string>"
      }
    ],
    "couldAnswer": true
  }
}

{
  "message": "The request could not be processed. Check the request body and required parameters."
}

{
  "message": "unauthorized"
}

{
  "status": "InternalServerError",
  "code": 500,
  "messages": [
    "Error occur. Please contact support with error ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  ]
}

Standard
Streaming

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. When includeCitations is true, the streamed answer includes inline Markdown citation links (e.g. [1](url)) for each source used. When false (default), the streamed answer has no inline citations, and a single primary source URL is surfaced separately instead. 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.

Filtering, boosting, and source fields

Three optional fields let you narrow and shape the content the model uses when generating an answer. All three work on both the standard and streaming endpoints.

Field	What it does
`filters`	Restricts the grounding documents to those matching a field/value filter — same syntax as the Search endpoint filters
`valueBoost`	Boosts documents where a field matches specific values, surfacing them higher in the context window
`sourceFields`	Controls which indexed fields are passed to the model as context (defaults to `Title` and `Content`)

curl -X POST "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer" \
  -H "Authorization: Basic <base64(customerId:apiKey)>" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is your return policy?",
    "filters": {
      "Category": ["Policies"]
    },
    "valueBoost": [
      {
        "fieldName": "ContentType",
        "boosts": [
          { "boost": 10, "values": ["FAQ"] }
        ]
      }
    ],
    "sourceFields": ["Title", "Content", "Summary"]
  }'

import requests, base64

credentials = base64.b64encode(b"customerId:apiKey").decode()

response = requests.post(
    "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer",
    headers={
        "Authorization": f"Basic {credentials}",
        "Content-Type": "application/json",
    },
    json={
        "question": "What is your return policy?",
        "filters": {
            "Category": ["Policies"]
        },
        "valueBoost": [
            {
                "fieldName": "ContentType",
                "boosts": [{"boost": 10, "values": ["FAQ"]}],
            }
        ],
        "sourceFields": ["Title", "Content", "Summary"],
    },
)
print(response.json())

const credentials = btoa("customerId:apiKey");

const response = await fetch(
  "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer",
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "What is your return policy?",
      filters: {
        Category: ["Policies"],
      },
      valueBoost: [
        {
          fieldName: "ContentType",
          boosts: [{ boost: 10, values: ["FAQ"] }],
        },
      ],
      sourceFields: ["Title", "Content", "Summary"],
    }),
  }
);
const data = await response.json();

const credentials = btoa("customerId:apiKey");

interface ValueBoost {
  fieldName: string;
  boosts: { boost: number; values: string[] }[];
}

const body = {
  question: "What is your return policy?",
  filters: {
    Category: ["Policies"],
  },
  valueBoost: [
    {
      fieldName: "ContentType",
      boosts: [{ boost: 10, values: ["FAQ"] }],
    },
  ] as ValueBoost[],
  sourceFields: ["Title", "Content", "Summary"],
};

const response = await fetch(
  "https://api.cludo.com/api/v4/{customerId}/{engineId}/search/answer",
  {
    method: "POST",
    headers: {
      Authorization: `Basic ${credentials}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  }
);
const data: unknown = await response.json();

Tagging requests for analytics

The optional tags field labels the context a question was asked from. Tags are stored on the analytics events for the request and do not change the answer. They work on both the standard and streaming endpoints. If you built AI Mode yourself, see Tagging AI Mode requests for the tag that makes its requests count as AI Mode.

{
  "question": "What is your return policy?",
  "tags": ["<string>"]
}

A request is never rejected because of its tags. Instead, the tags are sanitized:

Each tag is lower-cased, and characters other than a–z, 0–9 and _ are removed. This also removes surrounding whitespace.
Each tag is cut to 32 characters.
Empty tags, duplicate tags and entries that are not strings are dropped.
Only the first 5 tags are kept.
A tags value that is not an array is ignored.

Authorizations

Authorization

string

header

required

SiteKey authentication. Pass the full value including the SiteKey prefix: SiteKey <base64(customerId:engineId:searchKey)>. Example: SiteKey dGVzdDoxMjM0NTY3Ojk4NzY1.

Path Parameters

customerId

integer

required

Your Cludo account ID.

engineId

integer

required

Search engine ID.

Body

application/json

question

string

required

End-user question in natural language. Grounding content is retrieved from your indexed pages.

conversationId

string<uuid>

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

string

ISO-639-1 or simple locale code for answer language (e.g. en, da).

answerLength

enum<string>

comprehensive for longer explanations; concise for short answers.

Available options:

comprehensive,

concise

customPrompt

string

Extra system-style instructions (tone, disclaimers, formatting). Use sparingly; overrides can affect safety and quality.

includeCitations

boolean

For non-streaming AI Chat, when true, the JSON response includes citations with title, url, and snippet for each source used, and url is left empty. When false (default), citations is omitted and url holds a single primary source link instead. For streaming AI Chat, when true, inline Markdown citation links are included in the streamed text. When false (default), the streamed text has no inline citations and a single primary source URL is surfaced separately. Server default: False.

filters

object

Restrict the grounding content used to answer the question. Each key is an indexed field name mapped to allowed values (e.g. {"Category": ["Guides"]}). The reserved keys range, date, and geo_distance express numeric, date, and geo-distance filters — see the Search endpoint's Filter value formats for the full grammar.

Show child attributes

Example:

{ "Category": ["Guides"] }

valueBoost

object[]

Field boost configurations that influence the ranking of search results used as context for the answer. Each entry names an indexed field and a list of boost rules, where each rule pairs a numeric boost multiplier with the values that trigger it.

Show child attributes

sourceFields

string[]

Document fields to use as grounding context when generating the answer. Defaults to ["Title", "Content"] when omitted. Extend this list to include additional indexed fields (e.g. "Summary", "Description") so the model can draw on richer content.

Example:

["Title", "Content"]

Response

Successful AI Chat response.

value

object

Show child attributes

Overview

Search

AI

Content & Indexing

Tracking

Feedback

Search Tools

Multi-turn conversations

Filtering, boosting, and source fields

Tagging requests for analytics

Authorizations

Path Parameters

Body

Response

​Multi-turn conversations

​Filtering, boosting, and source fields

​Tagging requests for analytics

Authorizations

Path Parameters

Body

Response

Multi-turn conversations

Filtering, boosting, and source fields

Tagging requests for analytics