# Headband

> Headband is the retrieval control plane: one API across Meilisearch, Typesense, Elasticsearch and Visor, with per-index engine routing and bring-your-own-engine support.

## Start here
- Getting started (create an index, settings, documents, search, with curl): https://headband.dev/docs/getting-started
- Integrate guide (Next.js, plain JS, Node, Python, Drizzle sync): https://headband.dev/docs/integrate
- Authentication (the two key types and what each can do): https://headband.dev/docs/authentication
- Search API (POST /v1/search parameters, filters, facets, sort, matchingStrategy): https://headband.dev/docs/search
- Documents API (add, delete, bulk import, the 4 MiB limit and an import script): https://headband.dev/docs/documents
- Index settings (filterable, sortable, searchable fields): https://headband.dev/docs/index-settings
- Engine compatibility (what each engine needs before filters, facets and sorting work): https://headband.dev/docs/engine-compatibility
- React SDK (@headband/react hooks and components): https://headband.dev/docs/react-sdk
- Framework recipes (SvelteKit, Remix, Astro, Rails, Laravel, Django): https://headband.dev/docs/framework-recipes
- MCP server (read-only search tools for agents): https://headband.dev/docs/mcp-server
- Errors and rate limits: https://headband.dev/docs/errors

## Keys: which goes where
- API host: https://headband.dev. Send Authorization: Bearer <key> and a JSON body. Use the full URL: a relative /v1/search calls your own app.
- Search key, hb_src_...: search, multi-search and list indexes. Safe in a browser (NEXT_PUBLIC_ variables, page code). It reads every field you index, so leave private fields (emails, people's names, costs) out of documents, or set displayedAttributes on Meilisearch and Visor. attributesToRetrieve does not protect anything.
- Admin key, hb_adm_...: create indexes, write documents, change settings, read tasks. Server only: scripts, jobs, server routes. Never in a browser or a NEXT_PUBLIC_ variable.
- Order of work: create the index (POST /v1/indexes), set filterableAttributes and sortableAttributes before you filter, facet or sort on a field (PATCH /v1/indexes/{uid}/settings; Elasticsearch takes none and uses <field>.keyword), send documents, wait for each task (GET /v1/tasks/{taskUid}?index=...), then search.

## Limits
- A REST request body is at most 4 MiB: POST /v1/documents and /v1/bulk answer 413 payload_too_large above it. Send large imports in pieces.
- A 429 carries Retry-After in seconds: wait that long and retry. Writes share 100 requests a minute per key.
- One bad document (for example, no primary key) fails its whole batch in the task, after a 202. Check each task.
- Paging: send page and hitsPerPage, and build page links from totalPages, which counts only pages that can be fetched. limitCapped, maxTotalHits and totalHitsExact: false appear when an engine stops short. Search errors carry a code (invalid_search_filter, invalid_search_facets, invalid_search_sort, index_not_found) and say how to fix them.
- Multi-word queries on Meilisearch match fewer words by default (matchingStrategy "last"). Send matchingStrategy: "all" when every word must match.
- @headband/react on npm is 0.2.0. In 0.2.0 a RefinementList (or useRefinementList) renders without end and never searches: pin @headband/react@0.1.1 for a page with facet lists until 0.2.1 ships. Its components use Tailwind classes: with Tailwind v4 add @source "../node_modules/@headband/react"; to the CSS file that imports Tailwind.
- MCP: https://headband.dev/api/mcp over HTTP. Claude Code: claude mcp add --transport http headband https://headband.dev/api/mcp --header "Authorization: Bearer hb_src_...". Its tools only search and read; they cannot create indexes, write documents or change settings.

## Public resources
- Website: https://headband.dev/
- Documentation: https://headband.dev/docs
- A/B test engines (hosted assignment, experiment events): https://headband.dev/docs/ab-testing
- Example apps: https://github.com/ZVN-DEV/headband-examples
- Dedicated engines guide: https://headband.dev/docs/dedicated-engines
- Branches guide: https://headband.dev/docs/branches
- Visor guide: https://headband.dev/docs/visor
- Sync guide (early access): https://headband.dev/docs/sync
- CLI guide: https://headband.dev/docs/cli
- Pricing: https://headband.dev/pricing
- API health: https://headband.dev/v1/health
- Engine shootout: https://headband.dev/shootout
- Integrations and connector recipes: https://headband.dev/integrations
- Public connector catalog: https://headband.dev/catalog.json
- Public connector API: https://headband.dev/v1/connectors

## Products
- Sync (early access): keeps an index on a Meilisearch, Typesense or Elasticsearch dedicated engine in step with a Postgres database through logical replication (not Visor yet). Documents are defined in SQL. Manage it from the dashboard or /v1/sync with an org-scoped admin key.
- CLI: @headband/cli, with device-code login and commands for indexes, documents, search, keys, dedicated engines and schema migrations.
- Pricing: beta plans bill searches and stored data. Free ($0), Starter ($12/month), Pro ($69/month), Scale ($249/month). Free has hard caps; paid plans bill overage.

## Engines
- engine values: meilisearch, typesense, elasticsearch, visor. Pick one per index on POST /v1/indexes, or per dedicated engine on POST /v1/instances.
- visor is ZVN's own engine, run by Headband only (no bring-your-own config). It is offered in a region where a dedicated engine host runs it; elsewhere POST /v1/instances and a Visor index create answer 503 engine_not_available. Search takes mode: "instant" (default, as-you-type) or "retrieval" (BM25F, longer queries). Writes are synchronous. No vector search: /v1/hybrid-search answers keyword-only with fallback: true. Guide: https://headband.dev/docs/visor
- Engine capabilities: https://headband.dev/docs/engine-compatibility
- Same data in several engines (equivalent settings, Elasticsearch .keyword, what does not carry over): https://headband.dev/docs/multi-engine

## Authenticated resources
Private org, project, index, and document manifests are not exposed in this public file. Use GET /v1/llms-txt with a Headband API key to generate an authenticated llms.txt manifest for indexes your key can access.

## Notes for agents
Use the public documentation for integration guidance. Do not assume this public manifest grants access to private customer indexes or documents.