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. |
| country | string | — | Optional ISO-2 market. Missing, invalid, or OTH ranks globally. recently-viewed accepts it but ignores it for rank/cache. |
| 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
User-to-item (homepage)
POST https://api.recomnext.com/recommendations
{
"scenario": "homepage-for-you",
"userId": "customer-42",
"count": 8,
"country": "IN"
}Similar products (PDP)
{
"scenario": "pdp-similar-pc",
"itemId": "game-elden-ring",
"count": 6,
"returnProperties": true,
"includedProperties": ["attributes.name", "attributes.price", "attributes.coverUrl"]
}Cart upsell (multi-seed)
{
"scenario": "cart-upsell",
"itemIds": ["game-elden-ring", "game-hades"],
"userId": "customer-42",
"count": 6
}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.
When scenario autoRelaxFilters is on and clauses were dropped, the response may include optional filterRelaxation (droppedClauses, effectiveFilter,droppedEntireFilter). See Scenarios — Query planning for filter auto-relax.
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.