AI Summary API reference

AI Summary works with search to give you a quick, clear overview. After a search query, it gathers key details from the most relevant search results and turns them into a short summary. This reference details how to use the AI Summary REST API.

Receiving data from a search request first

The AI Summary feature uses an RAG (Retrieval‑Augmented Generation) model to create a summary of your content. That means an AI Summary request cannot be sent on its own. Before you can request a summary, you must:

1. Perform a normal Search API request for the user’s query.
2. From the search response, select a small set of the most relevant results (typically the top 5 results).
3. Grab the URLs from those search results and send them as sources in the AI Summary request.

The AI Summary endpoint needs real content sources to perform the summary. Those sources are identified by their result IDs (generally the URL) returned by the search response. If you do not provide URLs (sources), the endpoint doesn’t know which pages to use for generating the summary.

To perform a search request, see the Search API documentation. After you perform the search request, use the following properties from the search response to generate a summary:

• GenerativeAnswerAvailable (boolean): tells you whether a generative answer would be available for the given query. If true, you can follow up the search request with an AI Summary request.
• TypedDocuments(array): the results returned by the search. From these results, you will:
  • extract the result identifiers (generally the URL)
  • choose 3–5 top results
  • send those URLs as sources[].id in the AI Summary request
• QueryId (string): a unique ID for the query. This must be included in the AI Summary request to associate the summary with the original search.

Search → Summarize flow

1. Search
   • Call the Search API with the user’s query.
   • Confirm GenerativeAnswerAvailable is true.
2. Pick sources
   • Take the top 5 results from TypedDocuments.
   • Use each result’s URL as sources[].id.
   • Choose which fields to consider, typically Title and Description.
3. Summarize
   • Call the AI Summary endpoint with:
     • the same query
     • the selected sources (URLs + fields)
     • the queryId from the search response

Making an AI summary request

There are two available API endpoints to which you can send an AI Summary request. One is a normal REST API endpoint that returns a complete response with the full text of the summary. The other is a streaming endpoint that returns the summary in chunks as it is generated. This endpoint is more performant, but needs to be handled differently on the client. Mozilla provides detailed documentation on how to consume streams.

Authorization

Both API endpoints require an authorization header. Both endpoints support either SiteKey authorization or Basic authorization. If you are sending requests directly from the client to the endpoint, you should use SiteKey authorization which will not expose your Cludo API key to the client. The search API documentation has information on how to format the authorization header for both types.

API request protocol and URLs

Send requests for the normal REST endpoint to:

POST https://api.cludo.com/api/v4/{{customer_id}}/{{engine_id}}/search/summarize

Send requests for the streaming endpoint to:

POST https://api.cludo.com/api/v4/{{customer_id}}/{{engine_id}}/search/summarize/stream

Request body

The request body is the same regardless of which endpoint you use. The required and optional properties are described below.

Example request body

{
   "query": "crawler configurations",
   "sources": [
      {
         "id": "https://help.cludo.com/how-to/how-to-test-a-crawler",
         "fields": [
            "Title",
            "Description"
         ]
      },
      {
         "id": "https://help.cludo.com/feature-description/what-is-a-crawler",
         "fields": [
            "Title",
            "Description"
         ]
      },
      {
         "id": "https://help.cludo.com/faq/how-to-delete-a-crawler",
         "fields": [
            "Title",
            "Description"
         ]
      }
   ],
   "language": "da",
   "length": "concise",
   "queryId": "0e76b36a-30ef-4676-a6e0-e06935d07fac",
   "includeCitations": true
}

Responses

The streaming endpoint responds with just a single stream of text so there is no data model to worry about when handling the response. If you are new to streams, Mozilla provides detailed documentation on how to consume streams.

The normal REST endpoint responds with this data model. The summarySourceUrls is only included if includeCitations is set to true in the request body:

{
   "value": {
      "summary": "A crawler is a tool used to create ...",
      "summaryRequestId": "268ec5317ab54aa1b1982298b357e58a",
      "summaryId": "37d75cfb-4e93-471e-b33b-2fd3ee4b3eab",
      "summarySourceUrls": [
            "https://help.cludo.com/how-to/how-to-test-a-crawler",
            "https://help.cludo.com/feature-description/what-is-a-crawler",
            "https://help.cludo.com/faq/how-to-delete-a-crawler"
        ]
   }
}

Sending feedback for AI summaries

After you have shown an AI summary to your end user, you can optionally send feedback about that summary to Cludo. This allows you to track satisfaction and improve the quality of future summaries.

Send feedback requests to:

POST https://api.cludo.com/api/v4/{{customer_id}}/{{engine_id}}/search/summarize/feedback

Use the same authorization strategy (SiteKey or Basic) as for the other AI Summary endpoints.

Feedback Request body

Name	Type	Required	Description
rating	"positive" | "negative"	No	Overall user rating of the summary.
selectedReason	string	No	Optional label explaining the reason for the rating.
comment	string	No	Optional free-text comment from the user.
summaryId	string	No	The summaryId value returned from the AI Summary response.

Note: While all fields are optional, it is strongly recommended to include at least rating and summaryId so that feedback can be linked to a specific summary instance. The summaryId is returned in the normal REST AI Summary response as shown earlier in this article.

Example feedback request body

{
  "rating": "negative",
  "selectedReason": "Incorrect information",
  "comment": "The summary mixed up the pricing details for the Basic and Pro plans.",
  "summaryId": "37d75cfb-4e93-471e-b33b-2fd3ee4b3eab"
}