Skip to main content
POST
/
v1
/
chunks
/
search
Search Chunks Handler
curl --request POST \
  --url http://localhost:8000/v1/chunks/search \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "<string>",
  "search_type": "dense_only",
  "hybrid_profile": "hybrid",
  "dense_weight": 123,
  "sparse_weight": 123,
  "parent_path_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "tag_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "chunk_types": [
    "TEXT"
  ],
  "ingestion_time_after": "2023-11-07T05:31:56Z",
  "active_version_only": true,
  "top_k": 5,
  "score_threshold": 0.3,
  "with_document": false
}
'
[
  {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "path_part_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "content_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "content": "<string>",
    "chunk_type": "TEXT",
    "chunk_metadata": {
      "polygons": [
        {
          "page": 123,
          "polygon": {
            "x": 123,
            "y": 123,
            "width": 123,
            "height": 123
          }
        }
      ],
      "s3_urls": [
        "<string>"
      ],
      "summary": "<string>",
      "extracted_text_s3_uri": "<string>",
      "secondary_taxonomy": "picture",
      "sheet_name": "<string>",
      "block_type": "<string>",
      "source_uri": "<string>",
      "enriched_html": "<string>",
      "cell_range": "<string>",
      "dependency_summary": {},
      "formulas": [
        {}
      ],
      "key_cells": [
        {}
      ],
      "named_ranges": [
        {}
      ]
    },
    "parent_path_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "materialized_path": "<string>",
    "system_managed": true,
    "tenant_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "score": 123,
    "num_tokens": 123,
    "prev_sibling_path_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "next_sibling_path_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "asset_s3_urls": [
      "<string>"
    ],
    "document": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "document_type": "PDF",
      "document_origin": "SOURCE"
    },
    "document_version": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "version": 123,
      "name": "<string>"
    }
  }
]

Documentation Index

Fetch the complete documentation index at: https://docs.knowledgestack.ai/llms.txt

Use this file to discover all available pages before exploring further.

Headers

​
authorization
string | null

Cookies

​
ks_uat
string | null

Body

application/json

Request body for chunk search (dense vector, full-text BM25, or hybrid).

​
query
string
required

Search query text

Minimum string length: 1
​
search_type
enum<string>
default:dense_only

Search type: dense_only (semantic) or full_text (BM25 keyword), or hybrid (weighted dense+BM25)

Available options:
dense_only,
full_text,
hybrid
​
hybrid_profile
enum<string>
default:hybrid

Hybrid weighting preset: hybrid, dense, or sparse

Available options:
hybrid,
dense,
sparse
​
dense_weight
number | null

Optional explicit weight for the dense branch. Must be provided together with sparse_weight and overrides hybrid_profile.

​
sparse_weight
number | null

Optional explicit weight for the sparse branch. Must be provided together with dense_weight and overrides hybrid_profile.

​
parent_path_ids
string<uuid>[] | null

Path part IDs to search within (non-CHUNK types). Defaults to tenant's /shared.

​
tag_ids
string<uuid>[] | null

Filter by tag IDs (AND logic — chunks must have ALL specified tags)

​
chunk_types
enum<string>[] | null

Filter by chunk types (TEXT, TABLE, IMAGE, HTML, UNKNOWN). Only chunks matching one of the listed types are returned.

Minimum array length: 1

Type of chunk content.

Available options:
TEXT,
TABLE,
IMAGE,
HTML,
UNKNOWN
​
ingestion_time_after
string<date-time> | null

Only chunks ingested after this timestamp

​
active_version_only
boolean
default:true

Only return chunks from the active document version

​
top_k
integer
default:5

Number of results (1-50)

Required range: 1 <= x <= 50
​
score_threshold
number
default:0.3

Minimum similarity score

​
with_document
boolean
default:false

Include ancestor document_id and document_version_id in each result

Response

Successful Response

​
id
string<uuid>
required

Chunk ID

​
path_part_id
string<uuid>
required

PathPart ID

​
content_id
string<uuid>
required

ChunkContent ID

​
content
string
required

Chunk text content

​
chunk_type
enum<string>
required

Type of chunk content

Available options:
TEXT,
TABLE,
IMAGE,
HTML,
UNKNOWN
​
chunk_metadata
ChunkMetadata · object
required

Chunk metadata

​
parent_path_id
string<uuid>
required

Parent PathPart ID

​
materialized_path
string
required

Full materialized path from root

​
system_managed
boolean
required

Whether this chunk is system-managed

​
tenant_id
string<uuid>
required

Tenant ID

​
created_at
string<date-time>
required

Creation timestamp

​
updated_at
string<date-time>
required

Last update timestamp

​
score
number
required

Search ranking score returned by Qdrant

​
num_tokens
integer | null

Number of tokens in chunk content

​
prev_sibling_path_id
string<uuid> | null

Previous sibling PathPart ID

​
next_sibling_path_id
string<uuid> | null

Next sibling PathPart ID

​
asset_s3_urls
string[]

Presigned URLs to download the chunk's visual assets (6-hour validity)

​
document
ChunkDocumentResponse · object

Ancestor document info (populated when with_document=true)

​
document_version
ChunkDocumentVersionResponse · object

Ancestor document version info (populated when with_document=true)