Hybrid Search

Combine keyword search with vector similarity in a single request. Pass a pre-computed embedding vector alongside your text query, and the engine blends both signals. Works identically across Meilisearch, Typesense, and Elasticsearch.

POST/v1/hybrid-search

Unified keyword + vector search. Falls back to keyword-only when no vector is provided.

Auth admin or search keyReturns 200

Request body

{
  "index": "products",
  "q": "wireless headphones",
  "vector": [0.12, -0.34, 0.56, ...],
  "semanticRatio": 0.7,
  "limit": 20,
  "filter": "price < 200"
}

Response

{
  "hits": [...],
  "query": "wireless headphones",
  "processingTimeMs": 18,
  "estimatedTotalHits": 156
}

Parameter	Type	Default	Description
`index`	string	required	Index UID to search
`q`	string	""	Keyword query string
`vector`	number[]	—	Pre-computed embedding vector. Omit for keyword-only search
`semanticRatio`	number	—	Balance between keyword (0) and vector (1) results. Must be 0-1
`limit`	number	20	Maximum hits to return
`filter`	string	—	Filter expression in engine syntax

Note: Headband does not generate embeddings — you compute the vector using your own model (OpenAI, Cohere, etc.) and pass it in. This keeps the architecture simple and avoids vendor lock-in on embedding models.