Skip to main content
Once your catalog and events are flowing, you can begin requesting recommendations. This guide shows how to call the API directly and how to rely on the JavaScript SDK for convenience. The /recommendations endpoint requires an access token that includes the neuronsearchlab-api/read scope.

​
Choose a context and audience

Every request should specify the surface and user the results are meant for.
  • context_id ties the request to a configuration defined in the console (for example 101 for Homepage Recommendations).
  • user_id represents the end user who will see the results. Anonymous traffic can use a temporary UUID.
  • Optional filters and boosts allow you to respect inventory rules or promote specific items.
If you need help modeling contexts, review the Contexts guide.

​
Call the REST API

curl -X GET "https://api.neuronsearchlab.com/recommendations" \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "user_id=user-123" \
  --data-urlencode "context_id=101" \
  --data-urlencode "quantity=10"
Requests may also provide the same fields in a JSON body instead of the query string. The service merges both sources before validation with the following schema:
  • user_id (required): identifier for the end user. If omitted, the sub claim from the access token is used.
  • context_id (optional): numeric reference to a stored context configuration that can introduce conditional filtering or grouping.
  • quantity (optional): number of results to return. Defaults to the configured context quantity when not supplied.
  • entity_type, name, description (optional): override attributes saved with the user embedding. entity_type must be either User or Item.
Each call resolves the tenant from the access token claims, fetches recent user activity, generates or reuses an embedding, and performs a vector similarity search with any context conditions applied. The response includes the persisted embedding record, recommended items or grouped aggregates, the total count, and the time spent processing the request. Errors return JSON messages with an appropriate status code and never leave transactions open. See the endpoint reference for the detailed contract.

​
Use the JavaScript SDK

Install the SDK and authenticate it with your client credentials: 
npm install @neuronsearchlab/sdk

import { NeuronSearchLab } from '@neuronsearchlab/sdk';

const client = new NeuronSearchLab({
  clientId: process.env.NEURON_CLIENT_ID!,
  clientSecret: process.env.NEURON_CLIENT_SECRET!,
});

const { data } = await client.recommendations.list({
  userId: 'user-123',
  contextId: 101,
  limit: 10,
});
The SDK automatically exchanges credentials for an access token and retries transient failures. Explore more SDK capabilities in the SDK introduction.

​
Render and measure

Use the item metadata provided in each response to render cards, collections, or hero modules in your UI. Track downstream engagement with the POST /events endpoint and keep your catalog fresh with POST /items; both feed the signals that the recommendation service uses.