Unified Recommendations API
POST /recommendations is the primary contract for all logic types. Pass a scenario slug or explicit logicType with the required seed IDs.
API base URLs
| Engine API base URL | Admin UI |
|---|---|
| https://api.recomnext.com | https://admin.recomnext.com |
Use the engine base URL as baseUrl in widgets and SDKs.
Request body
| Setting | Type | Default | Description |
|---|---|---|---|
| scenario | string | — | Recommended. Resolves logicType, filters, boosters, constraints. |
| logicType | enum | — | Required if no scenario. user-to-item, item-to-item, etc. |
| userId | string | — | Required for user-to-item and recently-viewed. |
| itemId | string | — | Required for item-to-item and similar-products. |
| itemIds | string[] | — | Required for items-to-items. |
| count | number | 10 | Capped by scenario maxItems. |
| returnProperties | boolean | true | Full vs lean payload. |
| includedProperties | string[] | — | Exact raw paths when returnProperties true. |
| noCache | boolean | false | Skip cache read/write. |
Examples by logic type
Use case
User-to-item (homepage)
POST https://api.recomnext.com/recommendations
{
"scenario": "homepage-for-you",
"userId": "customer-42",
"count": 8
}Use case
Similar products (PDP)
{
"scenario": "pdp-similar-pc",
"itemId": "game-elden-ring",
"count": 6,
"returnProperties": true,
"includedProperties": ["attributes.name", "attributes.price", "attributes.coverUrl"]
}Use case
Cart upsell (multi-seed)
{
"scenario": "cart-upsell",
"itemIds": ["game-elden-ring", "game-hades"],
"userId": "customer-42",
"count": 6
}Use case
Logic only (no scenario — not recommended for production)
{
"logicType": "similar-products",
"itemId": "game-elden-ring",
"count": 8
}Uses default algorithm and no placement analytics. Prefer named scenarios for production traffic.
Response
{
"items": [
{
"itemId": "bundle-starter",
"category": "pc",
"attributes": {
"name": "Starter Bundle",
"price": 39.99
},
"score": 0.847
}
],
"count": 6,
"algorithm": "multi-seed-co-occurrence"
}score may be absent for some algorithms or lean modes. Guard UI access accordingly.
Authentication
| Setting | Type | Default | Description |
|---|---|---|---|
| Server | — | — | X-Api-Key or HMAC private signing. |
| Browser / widget | — | — | HMAC public token (publicToken). |
Legacy endpoints
GET routes per logic type remain for backward compatibility. Projection on GET uses query parameters that must be included in signed URLs — see Rendering payloads guide.