API reference · v1

Elements

Element endpoints of the XEYE API: single and batch creation of up to 10,000, updates, deletion and what triggers a retrain.

Updated on October 14, 2026

The element object

An element is a searchable entry: its text is what gets indexed and returned as item; description adds context for the model (and for the AI enrichment); params is an opaque text you store and get back untouched, meant for the SKU, the URL or the price.

Parameters
Field	In	Type	Required	Description
text	body	string	yes	What gets indexed and returned as item in the search (1–1,000 characters).
params	body	json	no	Any JSON value; stored as opaque text of up to 8,000 characters and returned by the search in every result.
description	body	string	no	Additional context for the model (up to 4,000 characters).

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 accepts any JSON value (object, array, string…) on create or update; it is stored as text of up to 8,000 characters and the response returns it as that string. The search delivers it decoded in every result.

Creating or deleting elements and changing text or description mark the list as pending training and the affected elements as trained: false; nothing launches on its own. Changing only params does not retrain: the search service reloads the list within seconds.

Endpoints

List elements

GEThttps://api.xeye.es/v1/lists/{listId}/elementsScope: lists:read

Page of the list elements, by ascending id, with a free-text filter on text and description.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
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 text and description.

Request

bash

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

Response

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
}

Create an element

POSThttps://api.xeye.es/v1/lists/{listId}/elementsScope: lists:write

One element. For more than a few, use the batch.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
text	body	string	yes	What gets indexed and returned as item in the search (1–1,000 characters).
params	body	json	no	Any JSON value; stored as opaque text of up to 8,000 characters and returned by the search in every result.
description	body	string	no	Additional context for the model (up to 4,000 characters).

Request

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

Response

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

Create elements in batch

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

1 to 10,000 elements and up to 16 MB per request, all or nothing: one invalid row rejects the whole batch with 400 and nothing is inserted. One pending training per batch. To sync a whole catalogue: delete in batches and load again.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
elements	body	object[]	yes	1 to 10,000 elements with the same fields as single creation.
elements[].text	body	string	yes	What gets indexed and returned as item in the search (1–1,000 characters).
elements[].params	body	json	no	Any JSON value; stored as opaque text of up to 8,000 characters and returned by the search in every result.
elements[].description	body	string	no	Additional context for the model (up to 4,000 characters).

Request

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

Response

201 Created · application/json

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

Delete elements in batch

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

Deletes the given ids that belong to the list and returns how many it deleted. Foreign or already deleted ids are ignored: repeating the call is safe.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
ids	body	integer[]	yes	1 to 10,000 ids of elements of the list.

Request

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

Response

200 OK · application/json

{ "deleted": 3 }

Get an element

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

One element. It must belong to the list in the path; otherwise 404.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
elementId	path	integer	yes	Element id; it must belong to the list in the path.

Request

bash

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

Response

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

Update an element

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

Partial: only the fields present change. params replaces the previous value entirely.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
elementId	path	integer	yes	Element id; it must belong to the list in the path.
text	body	string	no	What gets indexed and returned as item in the search (1–1,000 characters).
params	body	json	no	Any JSON value; stored as opaque text of up to 8,000 characters and returned by the search in every result.
description	body	string	no	Additional context for the model (up to 4,000 characters).

Request

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

Response

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

Delete an element

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

Deletes the element and leaves a pending training.

Parameters
Field	In	Type	Required	Description
listId	path	integer	yes	List id.
elementId	path	integer	yes	Element id; it must belong to the list in the path.

Request

bash

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

No response body (204 No Content).

Limits: text up to 1,000 characters, description up to 4,000, params up to 8,000 (as text), 10,000 elements and 16 MB per batch. There is no maximum number of elements per list; search quality and training price depend on the size.

Next: Trainings