Integer ID migration - NeuronSearchLab

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.

 {
   "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.

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

Upgrade server-side SDKs and stop emitting semantic identifiers.
Re-ingest or resolve catalogue records and persist the returned item IDs.
Deploy clients that submit integer event, item, and context IDs.
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.

​Breaking releases

​Update event tracking

​Keep source IDs separately

​Deployment order

Breaking releases

Update event tracking

Keep source IDs separately

Deployment order