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.
How it works
When you search, Knowledge Stack:
- Converts your query text into a vector embedding.
- Finds the most similar document chunks using vector similarity.
- Filters results by your specified scope and metadata.
- Enforces authorization — you only see results you have permission to read.
- Returns ranked results with similarity scores.
Search endpoint
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
| Parameter | Type | Default | Description |
|---|
query | string | (required) | Your search query in natural language. |
top_k | integer | 5 | Number of results to return (1-50). |
score_threshold | float | 0.3 | Minimum similarity score (0.0-1.0). Results below this score are excluded. |
parent_path_ids | list of UUIDs | tenant’s /shared folder | Restrict search to specific folders or documents by their path part IDs. |
chunk_type | string | all types | Filter by content type: TEXT, TABLE, IMAGE, or UNKNOWN. |
updated_at | datetime | none | Only 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 range | Meaning |
|---|
| 0.7 - 1.0 | Highly relevant — strong semantic match |
| 0.4 - 0.7 | Moderately relevant — related content |
| 0.3 - 0.4 | Loosely relevant — tangential match |
| Below 0.3 | Excluded by default (below threshold) |
score_threshold based on your use case. Lower it for broader recall, raise it for higher precision.
Scoping your search
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
}'
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
}'
Authorization and search
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 scope | Your permissions | What you see |
|---|
/shared/docs/projectA | Read access to /shared/docs | Results from /shared/docs/projectA |
/shared | Read access to /shared/docs and /shared/images | Results from both folders |
/shared/docs | Read access to /users/abc only | Empty list (no overlap) |
