Semantic Search

​

How it works

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

​

Response

• 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

​

Scoping your search

​

Search within specific folders

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
  }'

​

Filter by content type

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

• Owners and Admins can see results from anywhere in the tenant.
• Users only see results within their authorized paths.