> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getdecisional.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Chunks

> Returns raw retrieved chunks from a knowledge engine without streaming or workflow creation

Retrieve raw chunks from a knowledge engine without creating a workflow or generating a synthesized LLM answer.

### Request Format

<ParamField path="id" type="string" required>
  The knowledge engine ID to search.
</ParamField>

<ParamField body="query" type="string" required>
  The natural language query used to retrieve the most relevant chunks.
</ParamField>

<ParamField body="data_source_id" type="string">
  Optional. Restrict retrieval to a single data source.
</ParamField>

<ParamField body="top_k" type="integer">
  Maximum chunks to return. Defaults to `5`; values above `20` are clamped to `20`.
</ParamField>

### Response Format

<ResponseField name="query" type="string">
  The original query string.
</ResponseField>

<ResponseField name="knowledge_engine_id" type="string">
  The queried knowledge engine ID.
</ResponseField>

<ResponseField name="data_source_id" type="string">
  Returned when a single `data_source_id` was provided in the request.
</ResponseField>

<ResponseField name="chunks" type="array">
  Ranked chunks retrieved from the knowledge engine.

  <Expandable title="Chunk Object">
    <ResponseField name="content" type="string">
      The raw chunk text.
    </ResponseField>

    <ResponseField name="filename" type="string">
      The source filename, when available.
    </ResponseField>

    <ResponseField name="chunk_id" type="string">
      The chunk identifier returned by the retrieval system.
    </ResponseField>

    <ResponseField name="data_source_id" type="string">
      The source data source public ID for this chunk.
    </ResponseField>

    <ResponseField name="page_number" type="integer">
      Source page number for this chunk. Returns `-1` when not page-backed (for example, spreadsheet rows).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total_chunks" type="integer">
  Number of chunks returned.
</ResponseField>


## OpenAPI

````yaml POST /api/v1/knowledge-engines/{id}/retrieve
openapi: 3.0.1
info:
  title: Knowledge Engine API
  description: Public API endpoints for managing knowledge engines
  version: 1.0.0
servers:
  - url: https://api.getdecisional.ai
security: []
paths:
  /api/v1/knowledge-engines/{id}/retrieve:
    post:
      summary: Retrieve Chunks
      description: >-
        Returns raw retrieved chunks from a knowledge engine without streaming
        or workflow creation
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Knowledge engine ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - query
              properties:
                query:
                  type: string
                  description: The natural language query used to retrieve relevant chunks
                data_source_id:
                  type: string
                  description: >-
                    Optional data source ID to constrain retrieval to a single
                    source
                top_k:
                  type: integer
                  description: >-
                    Maximum number of chunks to return. Defaults to 5; values
                    above 20 are clamped to 20.
                  default: 5
                  minimum: 1
                  maximum: 20
      responses:
        '200':
          description: Retrieved chunks for the knowledge engine
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeEngineRetrieveResponse'
        '400':
          description: Bad Request - invalid IDs or malformed payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalid_knowledge_engine_id:
                  summary: Invalid Knowledge Engine ID
                  value:
                    error: Invalid knowledge engine ID
                invalid_data_source_id:
                  summary: Invalid Data Source ID
                  value:
                    error: Invalid data source ID
                mismatched_data_source_id:
                  summary: Data Source Ownership Mismatch
                  value:
                    error: Data source does not belong to this knowledge engine
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Unauthorized
        '404':
          description: Knowledge engine or data source not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Internal server error
components:
  schemas:
    KnowledgeEngineRetrieveResponse:
      type: object
      properties:
        query:
          type: string
          description: The original query string
        knowledge_engine_id:
          type: string
          description: Public ID of the queried knowledge engine
          example: kng_abc123xyz789
        data_source_id:
          type: string
          description: >-
            Public ID of the queried data source when request was scoped to one
            source
          example: ds_abc123xyz789
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeEngineRetrieveChunk'
        total_chunks:
          type: integer
          description: Number of chunks returned
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
          example: >-
            Invalid knowledge engine name: exceeds maximum length of 50
            characters
    KnowledgeEngineRetrieveChunk:
      type: object
      properties:
        content:
          type: string
          description: The raw chunk text
        filename:
          type: string
          description: The source filename when available
        chunk_id:
          type: string
          description: Identifier for the retrieved chunk
        data_source_id:
          type: string
          description: Public data source ID associated with the chunk
        page_number:
          type: integer
          description: >-
            Source page number for the chunk. Returns -1 for non-page-backed
            chunks (for example, spreadsheet rows).
          example: -1

````