API reference · v1

Lists

List endpoints of the XEYE API: create, read, update and delete lists, with examples in cURL, JavaScript and Python.

Updated on October 14, 2026

The list object

A list groups the elements that are searched together. Its name is the list_name of the search, so it should be unique within the account (the API does not enforce it yet). Only public lists can be searched with a key.

Parameters
Field	In	Type	Required	Description
name	body	string	yes	List name (1–100 characters); it is the list_name of the search.
description	body	string	no	Context the model receives when training (up to 2,000 characters). Changing it leaves a pending training.
is_public	body	boolean	no	Whether the list can be searched with an API key. Default false.
llm_enrichment	body	boolean	no	false = the list opts out of AI-generated descriptions when training (cheaper). Default 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

List lists

GEThttps://api.xeye.es/v1/listsScope: lists:read

Page of the account lists, by ascending id, with the element count of each one.

Parameters
Field	In	Type	Required	Description
offset	query	integer	no	First item of the page, from 0.
limit	query	integer	no	Page size, 1 to 200 (default 50).
q	query	string	no	Free text over name and description.
is_public	query	boolean	no	true = public only, false = private only; absent = all.

Request

bash

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

Response

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
}

Create a list

POSThttps://api.xeye.es/v1/listsScope: lists:write

The list is born empty and untrained. Every other field has a default.

Parameters
Field	In	Type	Required	Description
name	body	string	yes	List name (1–100 characters); it is the list_name of the search.
description	body	string	no	Context the model receives when training (up to 2,000 characters). Changing it leaves a pending training.
is_public	body	boolean	no	Whether the list can be searched with an API key. Default false.
llm_enrichment	body	boolean	no	false = the list opts out of AI-generated descriptions when training (cheaper). Default true.

Request

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
  }'

Response

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"
}

Get a list

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

One list with its element_count.

Parameters
Field	In	Type	Required	Description
id	path	integer	yes	List id.

Request

bash

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

Response

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"
}

Update a list

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

Partial: only the fields present change. Changing the description leaves a pending training (it is part of the model context); name and visibility reach the search service within seconds.

Parameters
Field	In	Type	Required	Description
id	path	integer	yes	List id.
name	body	string	no	List name (1–100 characters); it is the list_name of the search.
description	body	string	no	Context the model receives when training (up to 2,000 characters). Changing it leaves a pending training.
is_public	body	boolean	no	Whether the list can be searched with an API key. Default false.
llm_enrichment	body	boolean	no	false = the list opts out of AI-generated descriptions when training (cheaper). Default true.

Request

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
  }'

Response

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"
}

Delete a list

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

Deletes the list with all its elements and trainings. Irreversible; the search service stops serving it within seconds.

Parameters
Field	In	Type	Required	Description
id	path	integer	yes	List id.

Request

bash

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

No response body (204 No Content).

If two requests modify the same list at once, the second one gets 409 CONCURRENT_MODIFICATION: read it again and retry.

Next: Elements