> ## 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.

# Integer ID migration

> Upgrade events, items, and contexts to the numeric public ID contract.

The public API now accepts only integer identifiers for events, items, and contexts. This makes interaction data directly usable by recommendation and ML training pipelines without maintaining a second string-to-number encoding layer.

| Field                            | Source                                                    | Valid values                                                   |
| -------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------- |
| `eventId` / `event_id` / `event` | Event configuration in the NSL dashboard                  | A non-zero integer. Built-in events can use negative integers. |
| `itemId` / `item_id`             | The response from `POST /v1/items` or catalogue ingestion | A positive integer generated by NSL.                           |
| `contextId` / `context_id`       | Context configuration in the NSL dashboard                | A positive integer.                                            |

## Breaking releases

* JavaScript SDK: `2.0.0`
* Next.js SDK: `1.0.0`
* PHP SDK: `2.0.0`
* Swift SDK: `1.0.0`
* MCP server: `1.0.0`

## Update event tracking

Replace semantic event and item strings with IDs returned by NSL.

```diff theme={null}
 {
   "userId": "2048738e-38ec-4b68-8854-33703ed3b62f",
-  "itemId": "football-pressing",
-  "event": "click"
+  "itemId": 3187,
+  "eventId": 41,
+  "contextId": 236
 }
```

Unknown event, item, or context IDs are rejected. Event ingestion no longer stores an unknown item as `null`, because that would make the training record ambiguous.

## Keep source IDs separately

Do not send a CMS, SKU, article slug, or feed identifier as `itemId`. Put it in `metadata.source_item_id` when ingesting the item. Repeated ingestion with the same tenant and source ID updates the existing item and returns the same NSL-generated integer.

```ts theme={null}
const item = await nsl.syncContent({
  name: 'Football pressing explained',
  metadata: { source_item_id: 'football-pressing' },
});

await nsl.trackEvent({
  userId,
  itemId: item.id,
  eventId: clickEventId,
  contextId: homepageContextId,
});
```

Persist the returned `item.id` beside the source record. If that is not practical, calling item ingestion again with the same `metadata.source_item_id` safely resolves the same integer ID.

## Deployment order

1. Upgrade server-side SDKs and stop emitting semantic identifiers.
2. Re-ingest or resolve catalogue records and persist the returned item IDs.
3. Deploy clients that submit integer event, item, and context IDs.
4. Confirm event ingestion and recommendation responses, then retrain any model whose artifact encoded legacy item identifiers.

The NSL-hosted migration preserves a tenant-scoped legacy-to-integer mapping so historical events, recommendation snapshots, embeddings, and catalogue relationships remain joinable.