Getting Started

What is Headband?#

Headband is the retrieval control plane — the layer between your data, the search engines that index it, and the AI agents that consume it. One API across Meilisearch, Typesense, and Elasticsearch. Pick your engine per index, not per project. Bring your own infra. Headband stores routing metadata and analytics; documents are indexed into the engine selected for each index.

Every project gets automatic API keys, built-in CORS support for browser-side search, and a dashboard for managing indexes, documents, and settings. Run your catalog on Meilisearch, your logs on Elasticsearch, and your autocomplete on Typesense — all under the same project, same API key.

Per-index engines

Mix Meilisearch, Typesense, and Elasticsearch in one project.

Bring your own engine

Point any index at your own cluster; Headband stores routing metadata, not your source corpus.

Built for agents

llms.txt, RAG endpoints, and authenticated HTTP MCP.

Choose your path

Add search to a frameworkSync a database or appRun A/B/C engine testsBuild agent retrieval

Quick Start#

Get up and running in six steps. Replace the example URL with your Headband instance.

Data boundary

Headband stores routing metadata, encrypted engine configs, hashed API keys, usage, and analytics. Documents are indexed into the selected engine. BYOE keeps the search index in your engine; Platform Default uses the configured Headband-managed platform engine. Query analytics may include query text, filters, hit counts, latency, variants, and experiment metadata.

1

Create a project in the dashboard

You'll receive a project-scoped admin key (hb_adm_) and a search key (hb_src_) automatically.

2

Create an index

terminal
curl -X POST https://your-instance.com/v1/indexes \
  -H "Authorization: Bearer hb_adm_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"uid": "products", "primaryKey": "id", "engine": "meilisearch"}'
3

Configure searchable, filterable, and sortable fields

terminal
curl -X PATCH https://your-instance.com/v1/indexes/products/settings \
  -H "Authorization: Bearer hb_adm_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "searchableAttributes": ["title", "description"],
    "filterableAttributes": ["category", "price"],
    "sortableAttributes": ["price", "createdAt"]
  }'
4

Push your documents

terminal
curl -X POST https://your-instance.com/v1/documents?index=products&primaryKey=id \
  -H "Authorization: Bearer hb_adm_YOUR_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"id": 1, "title": "Widget", "price": 9.99},
    {"id": 2, "title": "Gadget", "price": 24.99}
  ]'
5

Poll returned task UIDs until async writes succeed

terminal
curl https://your-instance.com/v1/tasks/{taskUid} \
  -H "Authorization: Bearer hb_adm_YOUR_ADMIN_KEY"
6

Search

terminal
curl -X POST https://your-instance.com/v1/search \
  -H "Authorization: Bearer hb_src_YOUR_SEARCH_KEY" \
  -H "Content-Type: application/json" \
  -d '{"index": "products", "q": "widget", "filter": "price > 5", "sort": ["price:asc"]}'