How-To: Connect Catalog and Events

Use this guide when you need to keep item data current and user behavior signals flowing into NeuronSearchLab.

Setup

Choose item ID ownership

Decide whether your source catalog will provide stable item IDs or let NeuronSearchLab generate them.

Map source fields

Map source fields to /v1/items payloads (name, description, metadata).

Emit recommendation events

Emit user events to /v1/events from all recommendation surfaces.

Common workflows

Create catalog items

curl -X POST https://api.neuronsearchlab.com/v1/items \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "7f3a2c9e",
    "name": "Nike Running Shoes",
    "description": "High-performance running shoes.",
    "metadata": { "category": "Footwear", "brand": "Nike", "price": 109.99 }
  }'

Submit user interaction events

curl -X POST https://api.neuronsearchlab.com/v1/events \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user-456",
    "type": "click",
    "item_id": "7f3a2c9e",
    "context_id": "101",
    "occurred_at": 1777478400,
    "click": {}
  }'

Maintain ingestion quality

Validate required fields before publishing payloads.
Use Unix timestamps in integer seconds for event consistency.
Monitor event throughput and lag in your own pipeline metrics.

Example app journey: Daily sync + real-time feedback

Sync catalog records

Nightly job creates new catalog items using /v1/items and updates existing records with /v1/items/{id}.

Request recommendations

App session requests recommendations from the Core API recommendation endpoint.

Forward interactions

Frontend interaction events are forwarded to backend.

Publish events

Backend publishes click/purchase events to /v1/events in near real time.

Review analytics

Team reviews Analytics to confirm engagement trends are improving.

Get Started

Recommendation Control

NSL Connect

Console Workflow

Developer How-To

How-To: Connect Catalog and Events

Setup

Common workflows

Create catalog items

Submit user interaction events

Maintain ingestion quality

Example app journey: Daily sync + real-time feedback

Next steps

​Setup

​Common workflows

​Create catalog items

​Submit user interaction events

​Maintain ingestion quality

​Example app journey: Daily sync + real-time feedback

​Next steps

Setup

Common workflows

Create catalog items

Submit user interaction events

Maintain ingestion quality

Example app journey: Daily sync + real-time feedback

Next steps