Skip to main content

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.

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 official JavaScript or PHP SDK for convenience. Recommendation requests require 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 request filters let you narrow eligibility for a single call. Use the Rules Engine for durable promotion, suppression, grouping, or ordering logic.
If you need help modeling contexts, review the Contexts guide.

​
Call the REST API

curl -X GET "https://api.neuronsearchlab.com/v1/recommendations" \
  -H "Authorization: Bearer <access_token>" \
  -G \
  --data-urlencode "user_id=user-123" \
  --data-urlencode "context_id=101" \
  --data-urlencode "limit=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 (optional): identifier for the end user. If omitted, the sub claim from the access token is used.
  • context_id (optional): numeric console context ID. ctx_ aliases such as ctx_101 are accepted for backwards compatibility.
  • limit (optional): number of results to return. Defaults to 20 and is capped at 100.
  • 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, reuses the stored user embedding or a cold-start fallback, and performs vector similarity search with context and request filters applied. The response includes ranked recommendation objects, request_id, pagination fields, embedding information, explanations when available, and processing time. See the endpoint reference for the detailed contract.

​
Use the JavaScript SDK

Install the SDK and initialise it with an access token obtained from the auth token endpoint: 
npm install @neuronsearchlab/sdk

import NeuronSDK from '@neuronsearchlab/sdk';

const sdk = new NeuronSDK({
  baseUrl: 'https://api.neuronsearchlab.com/v1',
  accessToken: '<your_access_token>',
});

const result = await sdk.getRecommendations({
  userId: 'user-123',
  contextId: '101',
  limit: 10,
});

console.log(result.recommendations);
The SDK retries transient failures automatically with exponential backoff. Explore more SDK capabilities in the SDK introduction.

​
Use the PHP SDK

Install the PHP SDK from Packagist and initialize it with an access token obtained from the auth token endpoint: 
composer require neuronsearchlab/sdk-php

<?php

use NeuronSearchLab\NeuronSDK;

$sdk = new NeuronSDK([
    'baseUrl' => 'https://api.neuronsearchlab.com/v1',
    'accessToken' => '<your_access_token>',
]);

$result = $sdk->getRecommendations([
    'userId' => 'user-123',
    'contextId' => '101',
    'limit' => 10,
]);

var_dump($result['recommendations']);
The PHP SDK supports the same core recommendation, event, and catalog APIs. Explore more in the PHP SDK guide.

​
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 /v1/events endpoint and keep your catalog fresh with POST /v1/items; both feed the signals that the recommendation service uses.