Chat

RAG-grounded conversational search. Send a conversation history, and Headband retrieves relevant passages from your index, builds a grounded system prompt, and dispatches to your LLM provider. Bring Your Own Model — Headband never holds your LLM keys.

Chat Endpoint

POST/v1/chat

RAG-grounded conversational endpoint. Searches your index and generates an answer using your LLM provider.

Requires X-Headband-Provider-Key header with your LLM API key.

Auth admin or search keyReturns 200

Request body

{
  "index": "docs",
  "messages": [
    { "role": "user", "content": "How do I create an index?" }
  ],
  "provider": "openai",
  "model": "gpt-4o",
  "limit": 8
}

Response

{
  "answer": "To create an index, send a POST request to /v1/indexes...",
  "sources": [
    {
      "index": "docs",
      "id": "getting-started",
      "score": 0.95,
      "snippet": "Create an index by sending a POST request..."
    }
  ],
  "usage": {
    "promptTokens": 1240,
    "completionTokens": 180,
    "totalTokens": 1420
  },
  "model": "gpt-4o-2025-04-09",
  "processingTimeMs": 2340
}

Providers

Pass your LLM API key via the X-Headband-Provider-Key header. Headband supports two providers:

openaiOpenAI API key (sk-...)gpt-4o, gpt-4o-mini, gpt-3.5-turbo, etc.

anthropicAnthropic API key (sk-ant-...)claude-sonnet-4-20250514, claude-haiku, etc.

curl example

curl -X POST https://headband.dev/v1/chat \
  -H "Authorization: Bearer hb_your_key" \
  -H "X-Headband-Provider-Key: sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{
    "index": "docs",
    "messages": [{"role": "user", "content": "What is Headband?"}],
    "provider": "openai"
  }'

Conversations

Pass multi-turn conversation history via the messages array. Headband uses the latest user message as the retrieval query and injects retrieved passages into a system prompt. Caller-supplied system messages are stripped to preserve grounding integrity.

Parameter	Type	Default	Description
`index`	string	required	Index UID to search for grounding context
`messages`	array	required	Conversation history: [{role, content}]
`provider`	string	"openai"	'openai' or 'anthropic'
`model`	string	—	Model ID (e.g. 'gpt-4o'). Defaults to provider's latest
`limit`	number	8	Max passages to retrieve for grounding