Búsqueda

Las claves API autentican todas las llamadas a la API, la búsqueda incluida. Créalas desde la página Claves API con el permiso de búsqueda, 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 a /search con cuerpo JSON, autenticada con la cabecera X-API-Key. Solo sirve listas públicas.

El cuerpo es estricto: un campo desconocido, un término en blanco o un valor fuera de rango responden 422 con el detalle por campo.

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

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

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.

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 /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://api.xeye.es/v1/target \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "list_name": "products",
    "target_term": "Sony WH-1000XM5 wireless headphones",
    "session": "b1f2-…"
  }'

{ "success": true }

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 120 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.

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

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

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.