API

REST API

Everything the SDKs do is available over plain HTTP. Authenticate reads with a public API key header; every endpoint returns JSON (the answer endpoint streams server-sent events).

Authentication

Send your public key on every request. Public keys are read-only and validated against the origins you allow in the dashboard.

x-hopfield-public-api-key: hp_public_...

Search

GET /api/search/query

curl "https://hopfield.io/api/search/query?q=reset+password&limit=10" \
  -H "x-hopfield-public-api-key: hp_public_..."

q: the query (required).
collections: comma-separated collection IDs to search (defaults to all).
limit: max hits to return.

Returns { hits: [...] } where each hit includes url, title, description, the matched text, and a relevance score from hybrid semantic + keyword ranking.

Typeahead

GET /api/search/typeahead

curl "https://hopfield.io/api/search/typeahead?q=refun" \
  -H "x-hopfield-public-api-key: hp_public_..."

The endpoint is tuned for as-you-type latency. Returns hits grouped by collection: { query, groups: [{ collectionName, hits }], totalHits }.

AI answers (streaming)

POST /api/search/ask

curl -N "https://hopfield.io/api/search/ask" \
  -H "x-hopfield-public-api-key: hp_public_..." \
  -H "content-type: application/json" \
  -d '{"q": "how do refunds work?"}'

Streams server-sent events: delta events with answer text, a citations event with source documents, then done. The SDKs expose this as an async iterator.

Click tracking

POST /api/search/events/click

curl "https://hopfield.io/api/search/events/click" \
  -H "x-hopfield-public-api-key: hp_public_..." \
  -H "content-type: application/json" \
  -d '{"q": "reset password", "url": "https://your-site.com/help/reset"}'

Feeds the analytics dashboard (top queries, click-through, content gaps). The widget and SDKs send these automatically.

Writing to the index

Creating and deleting records uses the admin-authenticated indexing API.