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

# Generate Recommendations

> Request personalized results from the API or official JavaScript and PHP SDKs.

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](/contexts).

## Call the REST API

```bash theme={null}
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.
* `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](/api-reference/endpoint/get-recommendations) for the detailed contract.

## Use the JavaScript SDK

Install the SDK and initialise it with an access token obtained from the auth token endpoint:

```bash theme={null}
npm install @neuronsearchlab/sdk
```

```ts theme={null}
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](/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:

```bash theme={null}
composer require neuronsearchlab/sdk-php
```

```php theme={null}
<?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](/sdk/php).

## 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](/api-reference/endpoint/submit-events) and keep your catalog fresh with [`POST /v1/items`](/api-reference/endpoint/submit-items); both feed the signals that the recommendation service uses.