Search Knowledge

Search your knowledge base using hybrid, vector, or text search modes. Returns ranked results with relevance scores.

Search Modes

Mode	Description	Best For
`hybrid`	Combines vector + text with RRF fusion	Most queries (default)
`vector`	Pure semantic search	Conceptual questions
`text`	Keyword/BM25 search	Exact terms, SKUs, codes

Request

curl -X POST "https://platform.protobox.ai/api/v1/knowledge/search" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I return a product?",
    "mode": "hybrid",
    "limit": 5,
    "minScore": 0.7
  }'

curl -X POST "https://platform.protobox.ai/api/v1/knowledge/search" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Can I get my money back?",
    "mode": "vector",
    "limit": 3
  }'

curl -X POST "https://platform.protobox.ai/api/v1/knowledge/search" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SKU-12345",
    "mode": "text",
    "limit": 10,
    "source": "document",
    "category": "products"
  }'

const response = await fetch('https://platform.protobox.ai/api/v1/knowledge/search', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'How do I return a product?',
    mode: 'hybrid',
    limit: 5,
    minScore: 0.7
  })
});

const { data } = await response.json();
data.results.forEach(result => {
  console.log(`[${result.score.toFixed(2)}] ${result.title}`);
  console.log(`  ${result.content.substring(0, 100)}...`);
});

import requests

response = requests.post(
    'https://platform.protobox.ai/api/v1/knowledge/search',
    headers={'Authorization': f'Bearer {access_token}'},
    json={
        'query': 'How do I return a product?',
        'mode': 'hybrid',
        'limit': 5,
        'minScore': 0.7
    }
)

results = response.json()['data']['results']
for result in results:
    print(f"[{result['score']:.2f}] {result['title']}")

Response

{
  "success": true,
  "data": {
    "results": [
      {
        "id": "695c71705a8b2ca8d9016050",
        "title": "Return Policy",
        "content": "Our return policy allows returns within 30 days of purchase. Items must be unused and in original packaging. Refunds are processed within 5-7 business days.",
        "source": "manual",
        "metadata": {
          "category": "policies",
          "tags": ["returns", "refunds"]
        },
        "score": 0.92
      },
      {
        "id": "695c71705a8b2ca8d9016051",
        "title": "Refund Process",
        "content": "To request a refund, contact our support team with your order number. We'll process your request within 24 hours.",
        "source": "faq",
        "metadata": {
          "category": "support",
          "tags": ["refunds"]
        },
        "score": 0.85
      }
    ]
  }
}

{
  "success": true,
  "data": {
    "results": []
  }
}

Request Body

querystringrequired

Search query. Max 1000 characters.

modestringdefault: hybrid

Search mode: hybrid, vector, or text.

limitnumberdefault: 5

Maximum results to return. Range: 1-50.

minScorenumberdefault: 0.5

Minimum relevance score (0-1). Results below this threshold are filtered out.

sourcestring

Filter by source type: manual, document, webpage, faq, api_docs, transcript.

categorystring

Filter by category.

tagstring

Filter by tag.

Response

Each result contains:

Field	Type	Description
`id`	string	Entry ID
`title`	string	Entry title
`content`	string	Full content or chunk
`source`	string	Source type
`metadata`	object	Entry metadata
`score`	number	Relevance score (0-1)

Search Algorithm

Hybrid Search (Default)

Vector Search: Query is embedded using OpenAI, then matched against stored embeddings
Text Search: BM25-style full-text search on normalized content
RRF Fusion: Results are combined using Reciprocal Rank Fusion (k=60)
Deduplication: Duplicate entries are removed, keeping highest score

Vector Search

Uses OpenAI text-embedding-ada-002 (1536 dimensions)
Cosine similarity matching via MongoDB Atlas Vector Search
Falls back to text search if embeddings unavailable

Text Search

MongoDB text index with BM25-style scoring
Searches searchableText field (normalized lowercase)
Scores normalized to 0-1 range

Tips for Better Results

Lower minScore for exploratory queries. Default 0.5 works well, but try 0.3 for broader results.

Use vector mode for conceptual questions. "Can I get a refund?" finds return policy even without the word "return".

Use text mode for exact matches. Product codes, SKUs, and specific terms work best with text search.

Combine with filters. Narrow results by source, category, or tag for precision.

On this page