---
title: "Chunks Retrieval"
method: POST
path: "/v1/chunks"
tags: ["Context Chunks"]
---

# Chunks Retrieval

`POST /v1/chunks`

Given a `text`, returns the most relevant chunks from the ingested documents.

The returned information can be used to generate prompts that can be
passed to `/completions` or `/chat/completions` APIs. Note: it is usually a very
fast API, because only the Embeddings model is involved, not the LLM. The
returned information contains the relevant chunk `text` together with the source
`document` it is coming from. It also contains a score that can be used to
compare different results.

The max number of chunks to be returned is set using the `limit` param.

Previous and next chunks (pieces of text that appear right before or after in the
document) can be fetched by using the `prev_next_chunks` field.

The documents being used can be filtered using the `context_filter` and passing
the document IDs to be used. Ingested documents IDs can be found using
`/ingest/list` endpoint. If you want all ingested documents to be used,
remove `context_filter` altogether.

## Request body

- ChunksBody
  - `text` string, required
  - `context_filter` ContextFilter
    - `docs_ids` string[], nullable, required
  - `limit` integer
  - `prev_next_chunks` integer

## Response `200`

Successful Response

- ChunksResponse
  - `object` 'list', required
  - `model` 'private-gpt', required
  - `data` Chunk[], required
    - `object` 'context.chunk', required
    - `score` number, required
    - `document` IngestedDoc, required
      - `object` 'ingest.document', required
      - `doc_id` string, required
      - `doc_metadata` object, nullable, required
    - `text` string, required
    - `previous_texts` string[], nullable
    - `next_texts` string[], nullable

## Other responses

- `422` — Validation Error

## Changes

- **2023-11-29** `745b6d1eafa8` — 4 breaking, 8 info
  - the `data/items/document/object` response's property type changed from `string` to no type for status `200`
  - the `data/items/object` response's property type changed from `string` to no type for status `200`
  - the `model` response's property type changed from `string` to no type for status `200`
  - the `object` response's property type changed from `string` to no type for status `200`
  - …8 more

[Change history](https://skmtc.dev/zylon-ai/apis/private-gpt-api/changes/v1/chunks/post.md)

---

[API](https://skmtc.dev/zylon-ai/apis/private-gpt-api.md) · [All operations](https://skmtc.dev/zylon-ai/apis/private-gpt-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zylon-ai/private-gpt-api/revisions/fc0983573a3f/schema)