Integration

Recommendations

One endpoint, many strategies. POST /v1/recommend serves every use case; the strategy field picks the algorithm. Browser-safe with your publishable key.

Strategies

One endpoint, many algorithms: the strategy field routes the request. Every strategy also accepts optional filters (e.g. { "status": "active" }). If a request omits the input a strategy requires, the call returns 422 (see Errors); when there isn't enough signal to run, it degrades to the listed fallback.

Strategy	Requires	Fallback	What it does
`personalized`	`user_id`	Global trending	Ranks the catalog against the user's interest vector (semantic ANN search).
`similar`	`context_item_id`	Global trending	Nearest semantic neighbours to a context item; the item itself is excluded.
`frequently-bought-together`	`context_item_id`	Category popular	Complementary cross-sell from paired categories.
`frequently-consumed-together`	`context_item_id`	Category popular	Complementary items for the context item.
`session_based`	`user_id`	Global trending	Captures active session intent from the user's last ~5 interactions.
`session-resumption`	`user_id`	Global trending	Picks up a recent, interrupted session.
`abandonment-recovery`	`user_id`	Global trending	Alternatives for items viewed or carted but not purchased last session.
`serendipity`	`user_id`	Global trending	Breaks filter bubbles with controlled exploration of the user vector.
`trending`	none	Global random	Real-time popularity by weighted interaction velocity.
`popular`	none	Global random	Overall popularity; no user or item context needed.
`cold-start-booster`	`user_id`	Global trending	Boosts low-exposure (cold) items to increase their visibility.
`fresh-content-boost`	`user_id`	Global trending	Surfaces recently added catalog items.
`affinity-shift`	`user_id`	Global trending	Blends long-term preferences with short-term session intent by divergence.
`vibe-check`	`user_id`	Global trending	Like `affinity-shift`, with strict category alignment.

The endpoint

POSThttps://api.lehnz.com/v1/recommend

Request body

Field	Required	Description
strategy	No	One of the strategies above (default `personalized`).
user_id	No	The user to generate recommendations for. Required for user-based strategies.
context_item_id	No	The anchor item. Required for `similar` / `frequently-bought-together` / `frequently-consumed-together`.
filters	No	Optional attribute filters, e.g. `{ "category": "shoes" }`.
limit	No	Number of items to return (default: 20, max: 100).
page	No	1-indexed page number for pagination (default: 1).

The response data carries recommended_items (a flat list of item IDs), results (each with a score and reason), recommendation_id (for attribution), and pagination.

Cold start

Users with little or no history still get useful results: lean on trending, popular, or cold-start-booster. personalized sharpens as behavioral events accumulate.

Fetch recommendations

Request a ranked list for a user, hydrate the IDs with your own product data, and keep the recommendation_id for attribution.

curl -X POST https://api.lehnz.com/v1/recommend \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strategy": "personalized","user_id": "usr_8f3a2b9c","limit":12}'

Other strategies

Every use case is the same call: swap strategy and pass what it needs (see the table above). For frequently-bought-together send a cart context_item_id; for session_based send the user_id.

# Swap "strategy" and pass what it needs (see the table above).
curl -X POST https://api.lehnz.com/v1/recommend \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strategy": "similar","context_item_id": "itm_4d2e8a","limit":4}'

Attribute clicks & conversions

Attach the recommendation_id to your recommended items so the clicks and purchases they drive are credited back. See Tracking Events for the full event reference.

# Fire on click/purchase of a recommended item, echoing its recommendation_id.
curl -X POST https://api.lehnz.com/v1/ingest/events/ingest \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '[{"user_id": "usr_8f3a2b9c","event_family": "engagement","event_name": "click","item_id": "itm_4d2e8a","recommendation_id": "550e8400-e29b-41d4-a716-446655440000"}]'

Pagination

Use page to load more results; data.pagination.has_next tells you whether another page exists.

curl -X POST https://api.lehnz.com/v1/recommend \
  -H "X-API-KEY: lehnz_pk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"strategy": "personalized","user_id": "usr_8f3a2b9c","limit":12,"page":2}'

Errors

The recommendation service validates each request against the chosen strategy:

422 Unprocessable Entity. A required input is missing (e.g. similar without a context_item_id). The message names the field: { "success": false, "message": "Value error, The 'similar' strategy requires a context_item_id.", "data": null, "error": "..." }.
401 Unauthorized. X-API-KEY is missing or invalid: { "detail": "Invalid or missing API Key" }.