Getting started

Sign up, push, search.

In five minutes you'll have a hybrid-search API you can call from any language.

1 · Sign up and grab your API key

Create a free account. The first API key is generated automatically. Copy it — you'll only see the raw token once.

curl -X POST https://xrecommend.com/signup \
  -d "[email protected]" \
  -d "password=correct horse battery staple"

2 · Push a record

Records are arbitrary JSON. The title and body are embedded; metadata is filterable; the id is yours (or we'll generate one).

curl -X POST https://xrecommend.com/api/v1/collections/products/documents \
  -H "Authorization: Bearer xr_live_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "sku-001",
    "title": "Red running shoes",
    "body": "Lightweight mesh upper, breathable, summer-ready.",
    "metadata": { "price": 89.99, "category": "footwear", "tags": ["running"] }
  }'

3 · Search

curl -X POST https://xrecommend.com/api/v1/search \
  -H "Authorization: Bearer xr_live_••••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "lightweight summer shoes",
    "rerank": true,
    "top_k": 20
  }'

Each result comes back with a combined score and a per-signal signals breakdown so you can see why it ranked where it did.

4 · Tune the weights (optional)

Pass weights in the body to override the defaults. The four signals are dense, bm25, sparse, and kg.

curl -X POST https://xrecommend.com/api/v1/search \
  -H "Authorization: Bearer xr_live_••••••••••••••••" \
  -d '{ "q": "...", "weights": { "dense": 0.7, "bm25": 0.2, "sparse": 0.1, "kg": 0.0 } }'

Or use the search playground to drag the sliders live and watch the results re-rank.

Next steps