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

# Chunk retrieval

> Search indexed sources with keyword or semantic search and receive ranked chunks (text, page, bounding boxes).

Use `POST /retrieve/` to run **keyword** (full-text) or **semantic** (vector) search over your organization's indexed documents and return up to **`topk`** chunks. Results include the chunk text (`llm_context`), source filename, page reference, layout `bbox`, relevance `score`, and `chunk_id`.

Send your API key in the **`X-API-KEY`** header. Base URL is typically `https://api-prod.voltai.ai/source/api`.

## API key scope

This endpoint requires the **`retrieval`** permission on your API key when the key uses **granular scopes** (`allowed_permissions` in the admin). Keys with **empty** `allowed_permissions` keep full access (including retrieval). Keys scoped only to `sources`. **must** also include `retrieval` to call this route.

## Request body

* **`keyword`** (required) — Search string. Use document terms for `keyword` mode; short phrases or questions work well for `semantic` mode.
* **`search_mode`** (required) — `keyword` or `semantic`.
  * **`keyword`** — Elasticsearch full-text search over indexed chunk text.
  * **`semantic`** — Vector similarity search (Milvus) over embeddings.
* **`topk`** (optional) — Maximum chunks to return; default **10**, max **100**.

## Response

* **`chunks`** — Array of objects, each with:
  * **`filename`** — Source name.
  * **`page`** — Page number or list of pages, depending on how the chunk was split.
  * **`llm_context`** — Text content of the chunk.
  * **`bbox`** — Bounding box(es) for the region (format depends on source type).
  * **`score`** — Backend relevance score (may be `null` in edge cases).
  * **`chunk_id`** — Stable chunk identifier in the org's chunk store.

Chunks are sorted by descending relevance score when a score is present.

## Errors

* **400** — Invalid input (for example empty `keyword` after trimming, or invalid `search_mode`).
* **403** — Missing/invalid API key, or key lacks the **`retrieval`** scope.

## Example request

Set environment variable `API_KEY` to your key (same as for other Source API calls), then:

```bash theme={null}
curl -s -X POST "https://api-prod.voltai.ai/source/api/retrieve/" \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"EMC radiated emissions","search_mode":"keyword","topk":8}'
```

## Example response

```json theme={null}
{
  "chunks": [
    {
      "filename": "emc-guide.pdf",
      "page": 14,
      "llm_context": "Radiated emissions shall be measured at 3 m with a biconical antenna...",
      "bbox": [[72.0, 120.5, 540.0, 200.0]],
      "score": 0.91,
      "chunk_id": "abc123..."
    }
  ]
}
```

See also the [basic operations guide](/api-reference/knowledge-agent/source-api-basic-operations) for sources workflows before searching.


## OpenAPI

````yaml retrieval.json POST /retrieve/
openapi: 3.1.0
info:
  title: Document retrieval
  version: 1.0.0
  description: >-
    Search indexed organization content and return ranked text chunks with
    layout metadata.
servers:
  - url: https://api-prod.voltai.ai/source/api
security:
  - ApiKeyAuth: []
tags:
  - name: Retrieval
    description: Search indexed knowledge without invoking the chat agent.
paths:
  /retrieve/:
    post:
      tags:
        - Retrieval
      summary: Retrieve document texts
      description: >-
        Runs keyword search or semantic search over the organization's indexed
        sources, then returns up to `topk` texts.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetrievalRequest'
            examples:
              keyword:
                summary: Keyword search
                value:
                  keyword: GPIO interrupt mask
                  search_mode: keyword
                  topk: 10
              semantic:
                summary: Semantic search
                value:
                  keyword: How do I clear a pending interrupt?
                  search_mode: semantic
                  topk: 5
                  topic_uuid: 3fa85f64-5717-4562-b3fc-2c963f66afa6
      responses:
        '200':
          description: Ranked texts (may be empty if nothing matches).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetrievalResponse'
        '400':
          description: Invalid body (for example blank `keyword` or invalid `search_mode`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            Invalid or missing API key, or the key does not include the
            `retrieval` permission scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: >-
            `topic_uuid` was provided but no matching topic exists for the
            organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    RetrievalRequest:
      type: object
      required:
        - keyword
        - search_mode
      properties:
        keyword:
          type: string
          description: >-
            Search text. For `keyword` mode, use terms that appear in the
            documents; for `semantic` mode, short phrases or questions work
            well.
        search_mode:
          type: string
          enum:
            - keyword
            - semantic
          description: >-
            `keyword` — full-text search on indexed text. `semantic` — dense
            vector similarity search.
        topk:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
          description: Maximum number of texts to return.
        topic_uuid:
          type: string
          format: uuid
          nullable: true
          description: >-
            If set, restricts results to sources linked to this topic (including
            its subtree). Omit to search across all sources the key may access.
    RetrievalResponse:
      type: object
      required:
        - chunks
      properties:
        chunks:
          type: array
          items:
            $ref: '#/components/schemas/RetrievalChunk'
    Error:
      type: object
      description: Typical error payload (fields vary by case).
      additionalProperties: true
    RetrievalChunk:
      type: object
      properties:
        filename:
          type: string
          description: Source file name for the chunk.
        page:
          description: Page index or list of pages, as stored on the chunk.
          oneOf:
            - type: integer
            - type: array
              items:
                type: integer
            - type: 'null'
        llm_context:
          type: string
          description: Primary text content of the chunk.
        bbox:
          description: >-
            Bounding box coordinates for the chunk region on the page (structure
            depends on document type).
          type: array
        score:
          type: number
          nullable: true
          description: >-
            Relevance score from the search backend (higher is more relevant
            where applicable).
        chunk_id:
          type: string
          description: Identifier of the chunk in the organization's chunk collection.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        API key from organization settings. Must include the `retrieval` scope
        when the key uses granular permissions.

````