API integration

API keys authenticate calls to the search API. Create them from the API keys page, label them after where they are used, and rotate them by creating a new one and deleting the old.

A key gives access to the public lists of your account, and only those. Private lists are tried from the console's Search page (which uses your session, not a key). To let an integration query a list, mark it public.

Search is a single HTTP POST with a JSON body, authenticated with the X-API-Key header. It only serves public lists.

curl -X POST https://search.xeye.es/api/v1/search \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "list_name": "products",
    "search_term": "wireless headphones",
    "limit": 5
  }'

const response = await fetch('https://search.xeye.es/api/v1/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.XEYE_API_KEY,
  },
  body: JSON.stringify({
    list_name: 'products',
    search_term: 'wireless headphones',
    limit: 5,
    session: sessionId,          // optional: groups a user's searches
    include_score_breakdown: true,
  }),
})

const { results } = await response.json()

Results come sorted by score (0–1, higher is better). Each one carries the element text ("item"), its params untouched and, if requested, the text/semantic breakdown. duration_ms is the server-side search time.

{
  "success": true,
  "results": [
    {
      "item": "Sony WH-1000XM5 wireless headphones",
      "score": 0.93,
      "params": {
        "sku": "SONY-XM5",
        "url": "/products/sony-wh-1000xm5",
        "price": 348
      },
      "text_score": 0.71,
      "semantic_score": 0.96
    }
  ],
  "total_results": 1,
  "search_term": "wireless headphones",
  "list_name": "products",
  "duration_ms": 42,
  "degraded": false,
  "degradation_reasons": []
}

Every response carries degraded and degradation_reasons. When degraded is true the search was served with lower quality and the reason says why: no_embeddings (the list has no training in use: text only), model_unavailable (the embedding model could not be loaded), model_mismatch (the vectors do not match the model: retrain) or stale_data (stale data that could not be refreshed). The X-Search-Degraded: true header signals it too.

Optional. When the end user picks a result, send POST /api/v1/target with list_name, target_term (the chosen element text) and the same session as the search. It only records the choice in the history; nothing is searched. It answers {"success": true}.

curl -X POST https://search.xeye.es/api/v1/target \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "list_name": "products",
    "target_term": "Sony WH-1000XM5 wireless headphones",
    "session": "b1f2-…"
  }'

The searches-per-minute quota is per account: all your API keys (and the console playground) share it. The default is 60 searches/min; an administrator can set a different value for your account. There is also a per-IP limit applied before the key is checked.

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until the next window). Once the quota is exhausted you get 429 with Retry-After.

All errors share the same JSON body: status, error (HTTP phrase), code (a stable identifier for your code) and message (English text that may change); 422 responses add details with the reason per field. Branch on code, not on message.

HTTP/1.1 429 Too Many Requests
Retry-After: 23
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 23

{
  "status": 429,
  "error": "Too Many Requests",
  "code": "RATE_LIMITED",
  "message": "Rate limit of 60 requests per minute per account exceeded; retry in 23 seconds"
}