Search

Semantic search endpoints

Semantic Search#

Search across documents in a knowledge base using natural language.

knowledgebaseIdstringrequired

Knowledge base to search

querystringrequired

Natural language search query

topKinteger

Number of results to return (default: 10)

scoreThresholdnumber

Minimum similarity score (0-1, default: 0.5)

filterobject

Metadata filters

curl -X POST http://localhost:3000/api/v2/documents/search \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgebaseId": "kb-uuid",
    "query": "How do I configure authentication?",
    "topK": 5,
    "scoreThreshold": 0.6
  }'

Response#

{
  "results": [
    {
      "id": "chunk-uuid",
      "documentId": "doc-uuid",
      "filename": "auth-guide.pdf",
      "content": "Authentication is configured by setting the JWT_SECRET environment variable...",
      "score": 0.89,
      "metadata": {
        "page": 5,
        "section": "Configuration"
      }
    },
    {
      "id": "chunk-uuid-2",
      "documentId": "doc-uuid-2",
      "filename": "security.pdf",
      "content": "For secure authentication, use strong passwords and enable 2FA...",
      "score": 0.72,
      "metadata": {
        "page": 12,
        "section": "Security Best Practices"
      }
    }
  ],
  "query": "How do I configure authentication?",
  "totalResults": 2
}

Filtered Search#

Filter results by document metadata.

curl -X POST http://localhost:3000/api/v2/documents/search \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "knowledgebaseId": "kb-uuid",
    "query": "deployment procedures",
    "topK": 10,
    "filter": {
      "department": "Engineering",
      "documentType": "runbook"
    }
  }'

Filters match against document metadata extracted during processing.

Understanding Scores#

The score field indicates semantic similarity:

Score	Interpretation
0.90+	Very high relevance
0.75-0.89	High relevance
0.60-0.74	Moderate relevance
0.50-0.59	Low relevance
<0.50	Minimal relevance

Search Tips#

✅ "How do I reset a user's password?"
❌ "password reset user"

✅ "Configure JWT authentication in Node.js"
❌ "authentication"

✅ "Error handling for API rate limits"
❌ "error handling"

Error Responses#

Error	Status	Description
`KB_NOT_FOUND`	404	Knowledge base not found
`EMPTY_QUERY`	400	Query cannot be empty
`EMBEDDING_FAILED`	500	Failed to generate query embedding