Skip to main content

​
POST /api/search/semantic

Converts a natural-language query into a 768-dimension embedding using Gemini text-embedding-004, searches the Qdrant prism_documents collection for the nearest vectors (filtered to the specified user), and returns both a flat list of matching chunks and a grouped view organised by document. The route has a maximum execution time of 60 seconds.

​
Request body

​
query
string
required
Natural-language search query. The text is embedded by Gemini before being compared against stored vectors.
​
userId
string
required
Appwrite user ID. Restricts results to vectors belonging to this user.
​
documentType
string[]
Optional array of file type strings to filter results, e.g. ["PDF", "MD"]. When omitted, all file types are searched.
​
limit
number
default:"10"
Maximum number of individual chunk results to return from Qdrant.
​
scoreThreshold
number
default:"0.5"
Minimum cosine similarity score (0–1). Chunks below this threshold are excluded.

​
Response

{
  "success": true,
  "query": "quarterly revenue growth",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "score": 0.89,
      "documentId": "file_abc123",
      "chunkText": "Revenue grew 12% year-over-year in Q3…",
      "documentName": "q3-report.pdf",
      "documentType": "PDF",
      "category": "Financial",
      "chunkIndex": 3,
      "pageNumber": null,
      "section": null
    }
  ],
  "documents": [
    {
      "documentId": "file_abc123",
      "documentName": "q3-report.pdf",
      "documentType": "PDF",
      "category": "Financial",
      "maxScore": 0.89,
      "chunks": [
        { "chunkIndex": 3, "chunkText": "Revenue grew 12%…", "score": 0.89 }
      ]
    }
  ],
  "totalResults": 1,
  "totalDocuments": 1
}
​
success
boolean
true on success.
​
query
string
Echo of the search query.
​
results
object[]
Flat list of matching chunk objects, ordered by Qdrant’s default score ordering.
​
documents
object[]
Results grouped by document, sorted by maxScore descending. Useful for displaying one card per document with its best-matching chunks.
​
totalResults
number
Total number of individual chunk results.
​
totalDocuments
number
Number of unique documents that contain at least one matching chunk.

​
Errors

StatusCondition
400query or userId is missing
500Gemini embedding failed or Qdrant search failed

​
Example

curl -X POST https://<your-prism-domain>/api/search/semantic \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue growth",
    "userId": "user_abc123",
    "documentType": ["PDF"],
    "limit": 10,
    "scoreThreshold": 0.5
  }'

Build docs developers (and LLMs) love

Get started for freeTalk to us