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

> Generates a summary across selected search results for a given query.

<Tabs>
  <Tab title="Standard">
    You are viewing the **standard** endpoint which returns a complete JSON response.
    Generate AI-powered summaries from search result documents. The AI Summary endpoint works in tandem with the Search endpoint: first execute a search, then pass the search results as sources to generate a concise summary with citations.
  </Tab>

  <Tab title="Streaming">
    The streaming endpoint is the same path as standard with `/stream` appended:
    `POST /api/v4/{customerId}/{engineId}/search/summarize/stream`.
    It accepts the same request body as the standard endpoint, but streams the response as chunked plain text. Streaming responses set `Cludo-Summary-Id` and `Cludo-Summary-Request-Id` headers for tracking.
  </Tab>
</Tabs>

***

## Workflow

**Step 1: Execute a search**

Call the [Search](/api-reference/v4/search/search) endpoint and extract from the response:

* `QueryId` → use as the `queryId` parameter
* `TypedDocuments[].Fields.Id.Value` → use as the `id` for each source
* Source `fields` → prefer `Title` and `Content` when those fields are available

**Step 2: Generate the summary**

Pass the extracted values to this endpoint along with your query and source configuration. Send no more than 5 sources.

***

## Feature availability

<Note>
  **`answerLength` and `customPrompt` are in limited availability.** These options are currently in an early test phase and are only enabled for select customers running on specific servers. They are not active by default, so supplying these values will not change the generated output unless the features have been enabled for your account.

  To discuss enabling them for your setup, contact your account manager and share your customer ID and engine ID.
</Note>

<Note>
  **`includeCitations` applies to the streaming endpoint only.** This parameter has no effect on the standard summary response. Use the streaming endpoint (`/search/summarize/stream`) if you need source URLs included in the output.
</Note>


## OpenAPI

````yaml POST /api/v4/{customerId}/{engineId}/search/summarize
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/summarize:
    post:
      summary: AI Summary
      description: Generates a summary across selected search results for a given query.
      operationId: generateSummary
      parameters:
        - $ref: '#/components/parameters/customerId'
        - $ref: '#/components/parameters/engineId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AiSummaryRequest'
      responses:
        '200':
          description: AI Summary generated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AiSummaryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/SummaryUnprocessableEntity'
        '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:
    AiSummaryRequest:
      type: object
      required:
        - query
        - queryId
        - sources
      properties:
        query:
          type: string
          description: Original user query string from search (for context and analytics).
        queryId:
          type: string
          description: >-
            Must equal `QueryId` from the search response that produced
            `sources`.
        sources:
          type: array
          maxItems: 5
          items:
            $ref: '#/components/schemas/SummarySourceItem'
          description: >-
            One entry per result row to fold into the summary (typically the
            checked results on the SERP). Include at least three sources and no
            more than five.
          example:
            - id: https://help.cludo.com/...
              fields:
                - Title
                - Content
        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 shorter
            summaries. **Limited availability:** this feature is currently in an
            early test phase and is only enabled for select customers on
            specific servers. It is not active by default, so the value has no
            effect unless it has been enabled for your account. Contact your
            account manager (with your customer ID and engine ID) to discuss
            enabling it.
        customPrompt:
          type: string
          description: >-
            Optional extra instructions (e.g. “focus on steps”). **Limited
            availability:** this feature is currently in an early test phase and
            is only enabled for select customers on specific servers. It is not
            active by default, so the value has no effect unless it has been
            enabled for your account. Contact your account manager (with your
            customer ID and engine ID) to discuss enabling it.
        includeCitations:
          type: boolean
          description: >-
            When true, include source URLs in the value object
            (`summarySourceUrls`). **Streaming only:** this parameter applies
            only to the streaming endpoint (`/search/summarize/stream`) and has
            no effect on the standard summary response.
    AiSummaryResponse:
      type: object
      properties:
        value:
          $ref: '#/components/schemas/AiSummaryValue'
    SummarySourceItem:
      type: object
      required:
        - id
        - fields
      properties:
        id:
          type: string
          description: >-
            Document id from the search hit (same as in index / search
            response).
        fields:
          type: array
          items:
            type: string
          description: >-
            Which fields to pass into the summarizer. Prefer `Title` and
            `Content` when available so the model receives both page heading and
            body context.
    AiSummaryValue:
      type: object
      properties:
        summary:
          type: string
          description: Generated overview across the chosen sources.
        summaryRequestId:
          type: string
          description: Server id for this summarization job.
        summaryId:
          type: string
          description: >-
            Stable id for this summary text. Send this value to the feedback
            endpoint.
        summarySourceUrls:
          type: array
          items:
            type: string
          description: Pages the model relied on (for attribution UI).
    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.
  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
    SummaryUnprocessableEntity:
      description: >-
        AI Summary could not generate a useful summary from the provided
        sources. The request was well-formed and reached the model, but the
        search result content did not contain enough relevant context for the
        query. Treat this as a successful round-trip with no usable summary
        rather than retrying immediately.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            message: >-
              The provided sources did not contain enough relevant context to
              generate a summary.
    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 <base64(customerId:engineId:searchKey)>`. 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`.

````