Skip to main content

​
Description

This endpoint returns a list of recommended items for a given user, optionally using context-based logic to tailor results. It requires an access token that includes the neuronsearchlab-api/read scope.

​
Request

Endpoint: 
GET /recommendations
Headers: 
Authorization: Bearer <access_token>
Content-Type: application/json (when sending a body)

​
Request Parameters

Parameters may be supplied either as query parameters or in the JSON body. When both are present, they are merged with body values taking precedence.
NameTypeRequiredDescription
user_idstringyesIdentifier for the end user to personalize for. Falls back to the sub claim from the access token when omitted.
context_idintegernoIdentifier for an optional stored context that provides filters, groupings, and default limits.
quantityintnoNumber of recommendations to return. Defaults to the context configuration when not specified.
entity_typestringnoOverrides the embedding type saved for the entity. Must be User or Item.
namestringnoOverrides the name stored with the embedding.
descriptionstringnoOverrides the description stored with the embedding.
The handler resolves the tenant from the access token claims (client_id/sub) and rejects the request if the tenant lookup fails.

​
Response

200 OK 
{
  "embedding": {
    "entity_id": "user-456",
    "entity_type": "User",
    "name": "Avery",
    "description": "VIP shopper",
    "metadata": {
      "team_id": "team_123"
    }
  },
  "recommendations": [
    {
      "entity_id": "item-123",
      "score": 0.94,
      "embedding": [0.02, 0.31, -0.11],
      "metadata": {
        "name": "Nike Running Shoes",
        "brand": "Nike"
      },
      "group": null
    }
  ],
  "count": 1,
  "processing_time_ms": 182
}
When a context_id includes grouping configuration, the recommendations array contains grouped aggregates with representative metadata and scores. Scores are normalized to the range 0–1 (where higher is better).

​
Error responses

  • 400 Bad Request – Validation failed (for example, missing user_id or invalid entity_type).
  • 401 Unauthorized – Missing/invalid access token or tenant resolution failed.
  • 500 Internal Server Error – Unexpected errors. Transactions are rolled back and connections are closed safely in all cases.