Hybrid Search

GET

/v1/hybrid-search

Keyword-first search with automatic semantic fallback when keyword results are insufficient.

Hybrid search combines the speed of keyword matching with the intelligence of semantic search. It starts with a fast keyword search and automatically falls back to AI-powered semantic search if too few results are found.

How It Works

Step 1 — Keyword search: Performs a fast ILIKE match on business name and description_en fields
Step 2 — Evaluate results: Checks if keyword results count is below the keyword_min threshold
Step 3 — Semantic fallback: If results are below threshold, generates embeddings and runs vector similarity search
Step 4 — Deduplicate: Semantic results that already appeared in keyword results are removed
Step 5 — Return both: Response includes separate keyword_results and semantic_results arrays so you can distinguish the source

Query Parameters

Parameter	Type	Default	Description
`q`	string	—	Required. Search query string
`limit`	integer	10	Max results (1-50)
`keyword_min`	integer	3	Minimum keyword results before triggering semantic fallback
`category_id`	uuid	—	Filter by category (keyword search only)
`region_id`	uuid	—	Filter by region (keyword search only)

Example Request

cURLbash

curl "https://rjpxllsycikfabazvkdh.supabase.co/functions/v1/directory-api/v1/hybrid-search?q=sustainable%20packaging&limit=10&keyword_min=3" \
  -H "X-API-Key: your-key"

TypeScripttypescript

const results = await directoryApi(
  '/v1/hybrid-search?q=sustainable packaging&keyword_min=3'
);

console.log(`Keyword matches: ${results.keyword_count}`);
console.log(`Semantic matches: ${results.semantic_count}`);
console.log(`Used semantic fallback: ${results.used_semantic}`);

// Combine results for display
const allResults = [...results.keyword_results, ...results.semantic_results];

Response

{
  "query": "sustainable packaging",
  "keyword_results": [
    {
      "id": "uuid-1",
      "name": "EcoPack Bali",
      "slug": "ecopack-bali",
      "description_en": "Sustainable packaging solutions...",
      "verified": true
    }
  ],
  "semantic_results": [
    {
      "id": "uuid-2",
      "name": "Green Wrap Indonesia",
      "slug": "green-wrap-indonesia",
      "description_en": "Biodegradable wrapping and container manufacturer...",
      "similarity": 0.781
    }
  ],
  "keyword_count": 1,
  "semantic_count": 1,
  "used_semantic": true
}

When to Use Hybrid vs Semantic

Scenario	Recommended
Exact name/keyword lookup	`/v1/search` (keyword)
Natural language queries	`/v1/semantic-search`
General-purpose search with best coverage	`/v1/hybrid-search` ✓
AI agent context gathering	`/v1/semantic-search`

Semantic Search

Integrations

Last updated on March 15, 2026