Skip to main content

​
How it works

When you search, Knowledge Stack:
  1. Converts your query text into a vector embedding.
  2. Finds the most similar document chunks using vector similarity.
  3. Filters results by your specified scope and metadata.
  4. Enforces authorization — you only see results you have permission to read.
  5. Returns ranked results with similarity scores.

​
Search endpoint

POST /chunks/search

​
Request

curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "What is the deployment architecture?",
    "top_k": 10,
    "score_threshold": 0.4
  }'

​
Parameters

ParameterTypeDefaultDescription
querystring(required)Your search query in natural language.
top_kinteger5Number of results to return (1-50).
score_thresholdfloat0.3Minimum similarity score (0.0-1.0). Results below this score are excluded.
parent_path_idslist of UUIDstenant’s /shared folderRestrict search to specific folders or documents by their path part IDs.
chunk_typestringall typesFilter by content type: TEXT, TABLE, IMAGE, or UNKNOWN.
updated_atdatetimenoneOnly return chunks updated after this timestamp.

​
Response

The response is a list of matching chunks, sorted by relevance (highest score first). Each result includes:
  • Content — The actual text of the chunk.
  • Score — A similarity score between 0 and 1.
  • Path info — Where this chunk lives in the document hierarchy.
  • Metadata — Additional context like bounding boxes for PDF content and S3 URLs for images.

​
Understanding scores

Scores represent how similar a chunk is to your query:
Score rangeMeaning
0.7 - 1.0Highly relevant — strong semantic match
0.4 - 0.7Moderately relevant — related content
0.3 - 0.4Loosely relevant — tangential match
Below 0.3Excluded by default (below threshold)
Adjust score_threshold based on your use case. Lower it for broader recall, raise it for higher precision.

​
Search within specific folders

Pass parent_path_ids to restrict search to specific parts of your knowledge base: 
curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "quarterly revenue",
    "parent_path_ids": ["folder-path-part-id-1", "folder-path-part-id-2"],
    "top_k": 10
  }'
If you don’t specify parent_path_ids, the search defaults to your tenant’s /shared folder.

​
Filter by content type

Search only specific types of content: 
curl -X POST https://your-instance.example.com/api/v1/chunks/search \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "query": "revenue breakdown",
    "chunk_type": "TABLE",
    "top_k": 5
  }'
Search results are always filtered by your permissions. You will only see chunks from documents you have read access to.
  • Owners and Admins can see results from anywhere in the tenant.
  • Users only see results within their authorized paths.
If your requested search scope and your permissions don’t overlap, the search returns an empty list (not an error).
Your search scopeYour permissionsWhat you see
/shared/docs/projectARead access to /shared/docsResults from /shared/docs/projectA
/sharedRead access to /shared/docs and /shared/imagesResults from both folders
/shared/docsRead access to /users/abc onlyEmpty list (no overlap)