Listings sync

Structured inventory (cars, flats, products) the worker can search by attribute.

Knowledge sources are free text. Listings are rows: a price, a category, attributes. Use listings when the worker needs to answer "anything under 20k with automatic gearbox?" rather than "what's your return policy?".

Sync

POST/api/v1/listings/sync

Upsert by externalId. 1 to 1000 listings per request, request allowed 5 minutes.

listingsobject[]required

deleteStaleboolean

Delete listings not in this payload. Compared within the first item's category only, so send one category per request when using this.default false

Each listing:

externalIdstringrequired

titlestringrequired

descriptionstring

categorystring

pricenumber

≥ 0. Comes back as a string with two decimals.

currencystring

default EUR

attributesobject

Searchable key/values. { "gearbox": "automatic", "year": 2021 }.

sourceUrlurl

{
  "deleteStale": true,
  "listings": [
    {
      "externalId": "VIN-123",
      "title": "2021 Volvo XC60 B5",
      "category": "cars",
      "price": 34900,
      "attributes": { "gearbox": "automatic", "km": 61000, "fuel": "hybrid" },
      "sourceUrl": "https://example.com/cars/VIN-123"
    }
  ]
}

200

{
  "data": {
    "imported": 1, "updated": 0, "failed": 0, "deleted": 3,
    "results": {
      "imported": [{ "id": "…", "externalId": "VIN-123", "title": "2021 Volvo XC60 B5" }],
      "updated": [],
      "failed": []
    }
  },
  "meta": { "timestamp": "…", "message": "Synced: 1 created, 0 updated, 0 failed, 3 stale deleted" }
}

Embeddings are regenerated for every created or updated listing, synchronously. Validation errors come back as 400 with a details[] array of { path, message }.

Current state

GET/api/v1/listings/sync

Every active listing, up to 10 000, for diffing before a sync. Optional ?category= filter.

{
  "data": {
    "listings": [
      { "id": "…", "externalId": "VIN-123", "title": "…", "price": "34900.00", "status": "active", "sourceUrl": "…", "updatedAt": "…" }
    ],
    "total": 42
  },
  "meta": { "timestamp": "…" }
}

Sync

Current state

On this page