Integración por API

Las claves API autentican las llamadas a la API de búsqueda. Créalas desde la página Claves API, etiquétalas según dónde se usan y rótalas creando una nueva y borrando la antigua.

Una clave da acceso a las listas públicas de tu cuenta, y solo a ellas. Las listas privadas se prueban desde la página Búsqueda de la consola (que usa tu sesión, no una clave). Para que una integración pueda consultar una lista, márcala como pública.

La búsqueda es una única llamada HTTP POST con cuerpo JSON, autenticada con la cabecera X-API-Key. Solo sirve listas públicas.

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()

Los resultados vienen ordenados por puntuación (0–1, cuanto más alta mejor). Cada uno incluye el texto del elemento («item»), sus parámetros intactos y, si lo pediste, el desglose texto/semántica. duration_ms es el tiempo de búsqueda en el servidor.

{
  "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": []
}

Toda respuesta lleva degraded y degradation_reasons. Si degraded es true, la búsqueda se ha servido con menos calidad y el motivo lo dice: no_embeddings (la lista no tiene entrenamiento en uso: solo texto), model_unavailable (el modelo de embeddings no pudo cargarse), model_mismatch (los vectores no cuadran con el modelo: reentrena) o stale_data (datos caducos que no se pudieron refrescar). La cabecera X-Search-Degraded: true lo indica también.

Opcional. Cuando el usuario final elige un resultado, envía POST /api/v1/target con list_name, target_term (el texto del elemento elegido) y la misma session de la búsqueda. Solo registra la elección en el historial; no busca nada. Responde {"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-…"
  }'

El cupo de búsquedas por minuto es por cuenta: todas tus claves API (y el playground de la consola) lo comparten. Por defecto son 60 búsquedas/min; un administrador puede fijar otro valor para tu cuenta. Además hay un límite por dirección IP que se aplica antes de validar la clave.

Cada respuesta autenticada incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset (segundos hasta la siguiente ventana). Al agotarse el cupo recibes 429 con Retry-After.

Todos los errores comparten el mismo cuerpo JSON: status, error (frase HTTP), code (identificador estable para tu código) y message (texto en inglés que puede cambiar); los 422 añaden details con el motivo por campo. Decide por code, no por 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"
}