---
title: "Retrieve Chunks"
method: POST
path: "/retrieve/chunks"
---

# Retrieve Chunks

`POST /retrieve/chunks`

Retrieve relevant chunks.

The optional `request.filters` payload accepts equality checks (which also match scalars inside JSON arrays)
plus the logical operators `$and`, `$or`, `$nor`, and `$not`. Field-level predicates include `$eq`, `$ne`,
`$in`, `$nin`, `$exists`, `$type`, `$regex`, `$contains`, and the comparison operators `$gt`, `$gte`, `$lt`,
and `$lte`. Comparison clauses evaluate typed metadata (`number`, `decimal`, `datetime`, or `date`) and
raise detailed validation errors when operands cannot be coerced. Regex filters allow the optional `i` flag
for case-insensitive matching, while `$contains` performs substring checks (case-insensitive by default,
configurable via `case_sensitive`). Filters can be nested freely, for example:

```json
{
  "$and": [
    {"category": "policy"},
    {"$or": [{"region": "emea"}, {"priority": {"$in": ["p0", "p1"]}}]}
  ]
}
```
Returns a list of `ChunkResult` objects ordered by relevance.

## Headers

- `authorization` string, nullable

## Request body

- RetrieveRequest — Base retrieve request model
  - `query` string, nullable — Natural-language query used to retrieve relevant chunks or documents.
  - `query_image` string, nullable — Base64-encoded image to use as query for Morphik multimodal retrieval. Requires use_colpali=True. Mutually exclusive with 'query'.
  - `filters` object, nullable — Metadata filters supporting logical operators ($and/$or/$not/$nor) and field predicates ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$exists/$type/$regex/$contains).
  - `k` integer — Maximum number of chunks or documents to return.
  - `min_score` number — Minimum similarity score a result must meet before it is returned.
  - `use_reranking` boolean, nullable — When provided, overrides the workspace reranking configuration for this request.
  - `use_colpali` boolean, nullable — When provided, uses Morphik's finetuned ColPali style embeddings (recommended to be True for high quality retrieval).
  - `output_format` 'base64' | 'url' | 'text' — Output format for image chunks in retrieval results.
  - `padding` integer — Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only)
  - `folder_name` union — Optional folder scope. Accepts a folder PATH (e.g., '/Company/Reports') or list of paths.
    - string
    - string[]
  - `folder_depth` integer, nullable — Folder scope depth. 0 or None = exact folder only, -1 = include all descendants, n > 0 = include descendants up to n levels deeper.
  - `end_user_id` string, nullable — Optional end-user scope for the operation

## Response `200`

Successful Response

- ChunkResult[]
  - `content` string, required
  - `score` number, required
  - `document_id` string, required
  - `chunk_number` integer, required
  - `metadata` object, required
  - `content_type` string, required
  - `filename` string, nullable
  - `download_url` string, nullable
  - `is_padding` boolean — Whether this chunk was added as padding

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/morphik-org/apis/fastapi.md) · [All operations](https://skmtc.net/morphik-org/apis/fastapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/morphik-org/fastapi/versions/2d9291c3821d/schema)