> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How-To: Connect Catalog and Events

> Set up reliable item ingestion and event tracking for recommendation quality.

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

## Setup

<Steps>
  <Step title="Choose item ID ownership">
    Decide whether your source catalog will provide stable item IDs or let NeuronSearchLab generate them.
  </Step>

  <Step title="Map source fields">
    Map source fields to `/v1/items` payloads (`name`, `description`, `metadata`).
  </Step>

  <Step title="Emit recommendation events">
    Emit user events to `/v1/events` from all recommendation surfaces.
  </Step>
</Steps>

## Common workflows

### Create catalog items

```bash theme={null}
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

```bash theme={null}
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

<Steps>
  <Step title="Sync catalog records">
    Nightly job creates new catalog items using `/v1/items` and updates existing records with `/v1/items/{id}`.
  </Step>

  <Step title="Request recommendations">
    App session requests recommendations from the Core API recommendation endpoint.
  </Step>

  <Step title="Forward interactions">
    Frontend interaction events are forwarded to backend.
  </Step>

  <Step title="Publish events">
    Backend publishes click/purchase events to `/v1/events` in near real time.
  </Step>

  <Step title="Review analytics">
    Team reviews Analytics to confirm engagement trends are improving.
  </Step>
</Steps>

## Next steps

* [How-To: Serve Personalized Recommendations](./how-to-serve-recommendations)
* [POST /v1/items reference](/api-reference/endpoint/submit-items)
* [POST /v1/events reference](/api-reference/endpoint/submit-events)