Search Capability - WhizAI Documentation

Why This Exists

Traditional keyword search fails when users search with natural language or concepts. Semantic search understands meaning, not just keywords, enabling users to find content even when they don't use exact terms.

What It Is

Search is WhizAI's capability for semantic, hybrid, and vector similarity search. It uses AI embeddings to understand content meaning, enabling natural language queries and finding similar content based on concepts, not just keywords.

When to Use It

✅ Find content by meaning, not just exact keywords
✅ Enable natural language queries ("find articles about machine learning")
✅ Discover similar content using vector embeddings
✅ Combine semantic and keyword matching for best results
✅ Build content discovery features

Common use case: Product search that understands "wireless headphones" even when products are tagged as "bluetooth earbuds".

When NOT to Use It

❌ For exact keyword matching (use traditional search instead)
❌ When you haven't indexed your content (search requires content ingestion first)
❌ For very small content sets (semantic search shines with larger datasets)
❌ When you need sub-millisecond latency (semantic search adds ~50-200ms)

Best practice: Use hybrid search (semantic + keyword) for the best balance of relevance and performance.

Typical Use Cases

Content Discovery

Help users find articles, products, or documents using natural language queries.

Similarity Search

Find items similar to a given piece of content using vector embeddings.

Knowledge Base Search

Search across documentation, FAQs, or knowledge bases with semantic understanding.

Product Search

Enable customers to find products using descriptive queries, not just product names.

API Endpoints

Semantic Search

POST /v1/search/semantic

Required inputs:

query (string) - Natural language search query

Optional inputs:

limit (number) - Maximum results (default: 10, max: 100)
offset (number) - Pagination offset (default: 0)

Example request:

curl -X POST https://api.whizur.com/v1/search/semantic \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "machine learning algorithms",
    "limit": 10
  }'

Example response:

{
  "id": "search_123",
  "object": "semantic_search",
  "query": "machine learning algorithms",
  "results": [
    {
      "id": "doc_1",
      "title": "Introduction to ML",
      "content": "Machine learning is...",
      "similarity_score": 0.95,
      "category": "Technology"
    }
  ],
  "total_count": 25,
  "limit": 10,
  "offset": 0
}

Hybrid Search

POST /v1/search/hybrid

Combines semantic and keyword matching. Use when you want the best of both worlds.

Optional weights:

weights.semantic (default: 0.7)
weights.keyword (default: 0.3)

Vector Similarity Search

POST /v1/search/similarity

Find similar content using vector embeddings. Requires a pre-computed vector.

Default Behavior

Searches are scoped to your project (data isolation)
Results are ranked by relevance score (higher is better)
Empty collections return empty results (not an error)
Rate limits apply per API key

Data Ingestion

Before you can search, you need to ingest your content. Use the ingest endpoints to add content to your search index.

Content is automatically indexed for semantic search when ingested.

Billing & Usage

Each search query counts as one API call
Usage is tracked per API key
View usage in your dashboard

API Endpoint Documentation

For detailed API endpoint documentation with request/response schemas, interactive testing, and examples, see the Interactive API Reference.

The API reference includes all search endpoints: /v1/search/semantic, /v1/search/hybrid, and /v1/search/similarity.

Next Steps

Interactive API Reference Recommendations →