Referencia de la API · v1

Listas

Endpoints de listas de la API de XEYE: crear, consultar, modificar y borrar listas con ejemplos en cURL, JavaScript y Python.

Actualizado el 14 de octubre de 2026

El objeto lista

Una lista agrupa los elementos que se buscan juntos. Su nombre es el list_name de la búsqueda, así que conviene que sea único en la cuenta (la API no lo exige todavía). Solo las listas públicas se pueden buscar con una clave.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
name	cuerpo	string	sí	Nombre de la lista (1–100 caracteres); es el list_name de la búsqueda.
description	cuerpo	string	no	Contexto que recibe el modelo al entrenar (hasta 2000 caracteres). Cambiarla deja un entrenamiento pendiente.
is_public	cuerpo	boolean	no	Si la lista se puede buscar con una clave API. Por defecto false.
llm_enrichment	cuerpo	boolean	no	false = la lista renuncia a las descripciones generadas con IA al entrenar (más barato). Por defecto true.

application/json

{
  "id": 42,
  "name": "products",
  "description": "Online store catalogue: brand, category and price per item.",
  "is_public": true,
  "llm_enrichment": true,
  "element_count": 0,
  "created_at": "2026-10-14T09:12:03Z",
  "updated_at": "2026-10-14T09:12:03Z"
}

Endpoints

Listar listas

GEThttps://api.xeye.es/v1/listsÁmbito: lists:read

Página de listas de la cuenta, por id ascendente, con el número de elementos de cada una.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
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 nombre y descripción.
is_public	query	boolean	no	true = solo públicas, false = solo privadas; ausente = todas.

Petición

bash

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

Respuesta

200 OK · application/json

{
  "items": [ {
      "id": 42,
      "name": "products",
      "description": "Online store catalogue: brand, category and price per item.",
      "is_public": true,
      "llm_enrichment": true,
      "element_count": 0,
      "created_at": "2026-10-14T09:12:03Z",
      "updated_at": "2026-10-14T09:12:03Z"
    } ],
  "total": 1,
  "offset": 0,
  "limit": 20
}

Crear una lista

POSThttps://api.xeye.es/v1/listsÁmbito: lists:write

La lista nace vacía y sin entrenamiento. El resto de campos tiene valor por defecto.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
name	cuerpo	string	sí	Nombre de la lista (1–100 caracteres); es el list_name de la búsqueda.
description	cuerpo	string	no	Contexto que recibe el modelo al entrenar (hasta 2000 caracteres). Cambiarla deja un entrenamiento pendiente.
is_public	cuerpo	boolean	no	Si la lista se puede buscar con una clave API. Por defecto false.
llm_enrichment	cuerpo	boolean	no	false = la lista renuncia a las descripciones generadas con IA al entrenar (más barato). Por defecto true.

Petición

bash

curl -X POST https://api.xeye.es/v1/lists \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "products",
    "description": "Online store catalogue: brand, category and price per item.",
    "is_public": true
  }'

Respuesta

201 Created · application/json

{
  "id": 42,
  "name": "products",
  "description": "Online store catalogue: brand, category and price per item.",
  "is_public": true,
  "llm_enrichment": true,
  "element_count": 0,
  "created_at": "2026-10-14T09:12:03Z",
  "updated_at": "2026-10-14T09:12:03Z"
}

Obtener una lista

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

Una lista con su element_count.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
id	ruta	integer	sí	Id de la lista.

Petición

bash

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

Respuesta

200 OK · application/json

{
  "id": 42,
  "name": "products",
  "description": "Online store catalogue: brand, category and price per item.",
  "is_public": true,
  "llm_enrichment": true,
  "element_count": 0,
  "created_at": "2026-10-14T09:12:03Z",
  "updated_at": "2026-10-14T09:12:03Z"
}

Modificar una lista

PATCHhttps://api.xeye.es/v1/lists/{id}Ámbito: lists:write

Parcial: solo cambian los campos presentes. Cambiar la descripción deja un entrenamiento pendiente (forma parte del contexto del modelo); el nombre y la visibilidad llegan al buscador en segundos.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
id	ruta	integer	sí	Id de la lista.
name	cuerpo	string	no	Nombre de la lista (1–100 caracteres); es el list_name de la búsqueda.
description	cuerpo	string	no	Contexto que recibe el modelo al entrenar (hasta 2000 caracteres). Cambiarla deja un entrenamiento pendiente.
is_public	cuerpo	boolean	no	Si la lista se puede buscar con una clave API. Por defecto false.
llm_enrichment	cuerpo	boolean	no	false = la lista renuncia a las descripciones generadas con IA al entrenar (más barato). Por defecto true.

Petición

bash

curl -X PATCH https://api.xeye.es/v1/lists/42 \
  -H "X-API-Key: $XEYE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_public": false
  }'

Respuesta

200 OK · application/json

{
  "id": 42,
  "name": "products",
  "description": "Online store catalogue: brand, category and price per item.",
  "is_public": false,
  "llm_enrichment": true,
  "element_count": 0,
  "created_at": "2026-10-14T09:12:03Z",
  "updated_at": "2026-10-14T09:12:03Z"
}

Borrar una lista

DELETEhttps://api.xeye.es/v1/lists/{id}Ámbito: lists:write

Borra la lista con todos sus elementos y entrenamientos. Irreversible; el buscador deja de servirla en segundos.

Parámetros
Campo	Dónde	Tipo	Obligatorio	Descripción
id	ruta	integer	sí	Id de la lista.

Petición

bash

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

Sin cuerpo de respuesta (204 No Content).

Si dos peticiones modifican la misma lista a la vez, la segunda recibe 409 CONCURRENT_MODIFICATION: vuelve a leerla y repite.

Siguiente: Elementos