Retrieve Chunks Grouped

Retrieve relevant chunks with grouped response format.

Uses the same filter operators as /retrieve/chunks (equality, $eq/$ne, $gt/$gte/$lt/$lte, $in/$nin, $exists, $type, $regex, $contains, and the logical $and/$or/$nor/$not), with arbitrary nesting supported inside request.filters.

Returns both flat results (for backward compatibility) and grouped results (for UI). When padding > 0, groups chunks by main matches and their padding chunks.

POST /retrieve/chunks/grouped

JavaScript

JavaScript

import Morphik from 'morphik';

const client = new Morphik({
  apiKey: process.env['MORPHIK_API_KEY'], // This is the default and can be omitted
});

const response = await client.retrieve.chunks.createGrouped();

console.log(response.chunks);

200

{
  "chunks": [
    {
      "content": "<string>",
      "score": 123,
      "document_id": "<string>",
      "chunk_number": 123,
      "metadata": {},
      "content_type": "<string>",
      "filename": "<string>",
      "download_url": "<string>",
      "is_padding": false
    }
  ],
  "groups": [
    {
      "main_chunk": {
        "content": "<string>",
        "score": 123,
        "document_id": "<string>",
        "chunk_number": 123,
        "metadata": {},
        "content_type": "<string>",
        "filename": "<string>",
        "download_url": "<string>",
        "is_padding": false
      },
      "total_chunks": 123,
      "padding_chunks": [
        {
          "content": "<string>",
          "score": 123,
          "document_id": "<string>",
          "chunk_number": 123,
          "metadata": {},
          "content_type": "<string>",
          "filename": "<string>",
          "download_url": "<string>",
          "is_padding": false
        }
      ]
    }
  ],
  "total_results": 123,
  "has_padding": true
}

Headers

authorization · string | null

Body

application/json

Base retrieve request model

query · string | null

Natural-language query used to retrieve relevant chunks or documents.

Minimum string length: 1

query_image · string | null

Base64-encoded image to use as query for Morphik multimodal retrieval. Requires use_colpali=True. Mutually exclusive with 'query'.

filters · Filters · object | null

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 · default: 4

Maximum number of chunks or documents to return.

min_score · number · default: 0

Minimum similarity score a result must meet before it is returned.

use_reranking · boolean | null

When provided, overrides the workspace reranking configuration for this request.

use_colpali · boolean | null

When provided, uses Morphik's finetuned ColPali style embeddings (recommended to be True for high quality retrieval).

output_format · enum<string> | null · default: base64

How to return image chunks: base64 (default), url, or text (markdown format)

Available options: base64, url, text

padding · integer · default: 0

Number of additional chunks/pages to retrieve before and after matched chunks (ColPali only)

Required range: x >= 0

folder_name · string string[]

Optional folder scope. Accepts a folder PATH (e.g., '/Company/Reports') or list of paths.

folder_depth · integer | null

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 | null

Optional end-user scope for the operation

Response

200

application/json

Successful Response

Response that includes both flat results and grouped results for UI

chunks · ChunkResult · object[] · required

Flat list of all chunks (for backward compatibility)

Show child attributes

groups · ChunkGroup · object[] · required

Grouped chunks for UI display

Show child attributes

total_results · integer · required

Total number of unique chunks

has_padding · boolean · required

Whether padding was applied to any results