API reference

Every endpoint.

All endpoints live under /api/v1/, scoped to the API key's account, and authenticated with a bearer token.

Collections

POST /api/v1/collections

Create a new collection (logical bucket of documents).

curl -X POST https://xrecommend.com/api/v1/collections \
  -H "Authorization: Bearer xr_live_•••" \
  -d '{"name": "products"}'

GET /api/v1/collections

List your collections.

Documents

POST /api/v1/collections/:id/documents

Push 1..N records into a collection. Records are arbitrary JSON.

curl -X POST https://xrecommend.com/api/v1/collections/products/documents \
  -H "Authorization: Bearer xr_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      { "id": "sku-001", "title": "...", "body": "...", "metadata": { ... } }
    ]
  }'

GET /api/v1/collections/:id/documents

List / paginate documents in a collection.

DELETE /api/v1/documents/:id

Remove a single document.

Search

POST /api/v1/search

Hybrid search across the account's documents.

curl -X POST https://xrecommend.com/api/v1/search \
  -H "Authorization: Bearer xr_live_•••" \
  -H "Content-Type: application/json" \
  -d '{
    "q": "lightweight summer shoes",
    "collection_id": "products",
    "filter": { "metadata.price": { "lte": 100 } },
    "weights": { "dense": 0.4, "bm25": 0.3, "sparse": 0.2, "kg": 0.1 },
    "rerank": true,
    "top_k": 20
  }'