Referencia de la API · v1

Elementos

Endpoints de elementos de la API de XEYE: alta individual y por lotes de hasta 10 000, modificación, borrado y qué dispara un reentrenamiento.

Actualizado el 14 de octubre de 2026

El objeto elemento

Un elemento es una entrada buscable: su text es lo que se indexa y se devuelve como item; description añade contexto para el modelo (y para el enriquecimiento con IA); params es un texto opaco que guardas y recuperas tal cual, pensado para el SKU, la URL o el precio.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
text	cuerpo	string	sí	Lo que se indexa y se devuelve como item en la búsqueda (1–1000 caracteres).
params	cuerpo	json	no	Cualquier valor JSON; se guarda como texto opaco de hasta 8000 caracteres y la búsqueda lo devuelve en cada resultado.
description	cuerpo	string	no	Contexto adicional para el modelo (hasta 4000 caracteres).

application/json

{
  "id": 1001,
  "list_id": 42,
  "text": "Sony WH-1000XM5 wireless headphones",
  "params": "{\"sku\":\"SONY-XM5\",\"url\":\"/products/sony-wh-1000xm5\",\"price\":348}",
  "description": "Noise-cancelling over-ear headphones, 30h battery",
  "generated_description": null,
  "trained": false,
  "created_at": "2026-10-14T09:15:40Z",
  "updated_at": "2026-10-14T09:15:40Z"
}

params acepta cualquier valor JSON (objeto, array, cadena…) al crear o modificar; se guarda como texto de hasta 8000 caracteres y la respuesta lo devuelve como esa cadena. La búsqueda lo entrega decodificado en cada resultado.

Crear o borrar elementos y cambiar text o description marcan la lista como pendiente de entrenar y los elementos afectados como trained: false; nada se lanza solo. Cambiar solo params no reentrena: el buscador recarga la lista en segundos.

Endpoints

Listar elementos

GEThttps://api.xeye.es/v1/lists/{listId}/elementsÁmbito: lists:read

Página de elementos de la lista, por id ascendente, con filtro de texto libre sobre text y description.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
offset	query	integer	no	Primer elemento de la página, desde 0.
limit	query	integer	no	Tamaño de página, de 1 a 200 (50 por defecto).
q	query	string	no	Texto libre sobre text y description.

Petición

bash

curl -X GET https://api.xeye.es/v1/lists/42/elements?limit=50 \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "items": [ {
      "id": 1001,
      "list_id": 42,
      "text": "Sony WH-1000XM5 wireless headphones",
      "params": "{\"sku\":\"SONY-XM5\",\"url\":\"/products/sony-wh-1000xm5\",\"price\":348}",
      "description": "Noise-cancelling over-ear headphones, 30h battery",
      "generated_description": null,
      "trained": false,
      "created_at": "2026-10-14T09:15:40Z",
      "updated_at": "2026-10-14T09:15:40Z"
    } ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

Crear un elemento

POSThttps://api.xeye.es/v1/lists/{listId}/elementsÁmbito: lists:write

Un elemento. Para más de unos pocos, usa el lote.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
text	cuerpo	string	sí	Lo que se indexa y se devuelve como item en la búsqueda (1–1000 caracteres).
params	cuerpo	json	no	Cualquier valor JSON; se guarda como texto opaco de hasta 8000 caracteres y la búsqueda lo devuelve en cada resultado.
description	cuerpo	string	no	Contexto adicional para el modelo (hasta 4000 caracteres).

Petición

bash

curl -X POST https://api.xeye.es/v1/lists/42/elements \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Sony WH-1000XM5 wireless headphones",
    "params": {
      "sku": "SONY-XM5",
      "url": "/products/sony-wh-1000xm5",
      "price": 348
    },
    "description": "Noise-cancelling over-ear headphones, 30h battery"
  }'

Respuesta

201 Created · application/json

{
  "id": 1001,
  "list_id": 42,
  "text": "Sony WH-1000XM5 wireless headphones",
  "params": "{\"sku\":\"SONY-XM5\",\"url\":\"/products/sony-wh-1000xm5\",\"price\":348}",
  "description": "Noise-cancelling over-ear headphones, 30h battery",
  "generated_description": null,
  "trained": false,
  "created_at": "2026-10-14T09:15:40Z",
  "updated_at": "2026-10-14T09:15:40Z"
}

Crear elementos por lotes

POSThttps://api.xeye.es/v1/lists/{listId}/elements/batchÁmbito: lists:write

De 1 a 10.000 elementos y hasta 16 MB por petición, todo o nada: una fila inválida rechaza el lote entero con 400 y no se inserta nada. Un solo entrenamiento pendiente por lote. Para sincronizar un catálogo entero: borra por lotes y vuelve a cargar.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
elements	cuerpo	object[]	sí	De 1 a 10 000 elementos con los mismos campos que la creación individual.
elements[].text	cuerpo	string	sí	Lo que se indexa y se devuelve como item en la búsqueda (1–1000 caracteres).
elements[].params	cuerpo	json	no	Cualquier valor JSON; se guarda como texto opaco de hasta 8000 caracteres y la búsqueda lo devuelve en cada resultado.
elements[].description	cuerpo	string	no	Contexto adicional para el modelo (hasta 4000 caracteres).

Petición

bash

curl -X POST https://api.xeye.es/v1/lists/42/elements/batch \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "elements": [
      {
        "text": "Sony WH-1000XM5 wireless headphones",
        "params": {
          "sku": "SONY-XM5",
          "price": 348
        }
      },
      {
        "text": "Bose QuietComfort Ultra headphones",
        "params": {
          "sku": "BOSE-QCU",
          "price": 429
        }
      }
    ]
  }'

Respuesta

201 Created · application/json

{
  "created": 2,
  "items": [ { "id": 1001, "list_id": 42, "text": "Sony WH-1000XM5 wireless headphones", "trained": false, "...": "..." }, { "id": 1002, "...": "..." } ]
}

Borrar elementos por lotes

POSThttps://api.xeye.es/v1/lists/{listId}/elements/batch-deleteÁmbito: lists:write

Borra los ids indicados que pertenezcan a la lista y devuelve cuántos borró. Los ids ajenos o ya borrados se ignoran: repetir la llamada es seguro.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
ids	cuerpo	integer[]	sí	De 1 a 10 000 ids de elementos de la lista.

Petición

bash

curl -X POST https://api.xeye.es/v1/lists/42/elements/batch-delete \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ids": [
      1001,
      1002,
      1003
    ]
  }'

Respuesta

200 OK · application/json

{ "deleted": 3 }

Obtener un elemento

GEThttps://api.xeye.es/v1/lists/{listId}/elements/{elementId}Ámbito: lists:read

Un elemento. Debe pertenecer a la lista de la ruta; si no, 404.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
elementId	ruta	integer	sí	Id del elemento; debe pertenecer a la lista de la ruta.

Petición

bash

curl -X GET https://api.xeye.es/v1/lists/42/elements/1001 \
  -H "X-API-Key: $XEYE_API_KEY"

Respuesta

200 OK · application/json

{
  "id": 1001,
  "list_id": 42,
  "text": "Sony WH-1000XM5 wireless headphones",
  "params": "{\"sku\":\"SONY-XM5\",\"url\":\"/products/sony-wh-1000xm5\",\"price\":348}",
  "description": "Noise-cancelling over-ear headphones, 30h battery",
  "generated_description": null,
  "trained": false,
  "created_at": "2026-10-14T09:15:40Z",
  "updated_at": "2026-10-14T09:15:40Z"
}

Modificar un elemento

PATCHhttps://api.xeye.es/v1/lists/{listId}/elements/{elementId}Ámbito: lists:write

Parcial: solo cambian los campos presentes. params sustituye el anterior completo.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
elementId	ruta	integer	sí	Id del elemento; debe pertenecer a la lista de la ruta.
text	cuerpo	string	no	Lo que se indexa y se devuelve como item en la búsqueda (1–1000 caracteres).
params	cuerpo	json	no	Cualquier valor JSON; se guarda como texto opaco de hasta 8000 caracteres y la búsqueda lo devuelve en cada resultado.
description	cuerpo	string	no	Contexto adicional para el modelo (hasta 4000 caracteres).

Petición

bash

curl -X PATCH https://api.xeye.es/v1/lists/42/elements/1001 \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "params": {
      "sku": "SONY-XM5",
      "url": "/products/sony-wh-1000xm5",
      "price": 329,
      "stock": 12
    }
  }'

Respuesta

200 OK · application/json

{
  "id": 1001,
  "list_id": 42,
  "text": "Sony WH-1000XM5 wireless headphones",
  "params": "{\"sku\":\"SONY-XM5\",\"url\":\"/products/sony-wh-1000xm5\",\"price\":329,\"stock\":12}",
  "description": "Noise-cancelling over-ear headphones, 30h battery",
  "generated_description": null,
  "trained": false,
  "created_at": "2026-10-14T09:15:40Z",
  "updated_at": "2026-10-14T09:15:40Z"
}

Borrar un elemento

DELETEhttps://api.xeye.es/v1/lists/{listId}/elements/{elementId}Ámbito: lists:write

Borra el elemento y deja un entrenamiento pendiente.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
listId	ruta	integer	sí	Id de la lista.
elementId	ruta	integer	sí	Id del elemento; debe pertenecer a la lista de la ruta.

Petición

bash

curl -X DELETE https://api.xeye.es/v1/lists/42/elements/1001 \
  -H "X-API-Key: $XEYE_API_KEY"

Sin cuerpo de respuesta (204 No Content).

Límites: text hasta 1000 caracteres, description hasta 4000, params hasta 8000 (como texto), 10.000 elementos y 16 MB por lote. No hay máximo de elementos por lista; la calidad de la búsqueda y el precio del entrenamiento dependen del tamaño.

Siguiente: Entrenamientos