Search & Filtering

Basic Search

Send a natural language query and get ranked results:

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases/KB_ID/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "How do I reset my password?", "top_k": 5 }'

TypeScript

const results = await client.search(kbId, {
  query: 'How do I reset my password?',
  top_k: 5,
});

Python

results = client.search(kb_id, query="How do I reset my password?", top_k=5)

Metadata Filtering

Filter search results by document metadata using operator-based filters. Filters are applied after vector search, narrowing the result set to chunks from matching documents.

Filter Operators

Operator	Description	Example
$eq	Equal to	{"status": {"$eq": "published"}}
$ne	Not equal to	{"status": {"$ne": "draft"}}
$gt	Greater than	{"version": {"$gt": 1}}
$gte	Greater than or equal	{"version": {"$gte": 2}}
$lt	Less than	{"priority": {"$lt": 5}}
$lte	Less than or equal	{"priority": {"$lte": 3}}
$in	In array	{"department": {"$in": ["eng", "ops"]}}
$nin	Not in array	{"department": {"$nin": ["hr"]}}

Filter Examples

Single filter:

cURL

curl -X POST https://api.useragex.com/api/v1/knowledge-bases/KB_ID/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication setup",
    "filter": {
      "department": { "$eq": "engineering" }
    }
  }'

TypeScript

const results = await client.search(kbId, {
  query: 'authentication setup',
  filter: { department: { $eq: 'engineering' } },
});

Python

results = client.search(
    kb_id,
    query="authentication setup",
    filter={"department": {"$eq": "engineering"}},
)

Multiple filters (AND logic):

{
  "query": "security best practices",
  "filter": {
    "department": { "$eq": "engineering" },
    "version": { "$gte": 2 },
    "language": { "$in": ["en", "es"] }
  }
}

All filter conditions must match (AND). There is no OR operator at the top level.

Score Threshold

Set a minimum relevance score to filter out low-quality matches:

{
  "query": "API rate limiting",
  "score_threshold": 0.5
}

Scores range from 0 to 1. A threshold of 0.5 is a reasonable starting point. Experiment with your data to find the right value.

Reranking

Reranking is enabled by default. A cross-encoder model re-scores the top candidates for better accuracy.

To disable reranking (lower latency, slightly lower quality):

{
  "query": "deployment instructions",
  "rerank": false
}

The response tells you whether reranking was applied:

{
  "usage": {
    "rerank_applied": true,
    "embedding_tokens": 8,
    "chunks_searched": 42
  }
}

If the reranker times out or errors, results are still returned with rerank_applied: false.

Controlling Result Count

Use top_k to control how many results are returned (1-50, default 10):

{
  "query": "onboarding process",
  "top_k": 3
}

For RAG use cases, 3-5 results usually provide enough context for an LLM without excessive noise.

Common Patterns

Multi-tenant search

Upload documents with a tenant_id in metadata, then filter at query time:

{
  "query": "billing FAQ",
  "filter": { "tenant_id": { "$eq": "customer_123" } }
}

Version-aware search

Only search the latest version of your docs:

{
  "query": "configuration options",
  "filter": { "version": { "$eq": "latest" } }
}

Language filtering

Restrict results to a specific language:

{
  "query": "comment configurer l'authentification",
  "filter": { "language": { "$eq": "fr" } }
}