Unified Recommendation Endpoint

The primary way to fetch recommendations. Dispatches to the appropriate algorithm based on scenario or explicit logicType.

Request Body

Example

curl -X POST http://localhost:3000/recommendations \
  -H "Content-Type: application/json" \
  -H "X-Tenant-Id: demo-ecommerce" \
  -d '{
    "scenario": "homepage-for-you",
    "userId": "user-123",
    "count": 8,
    "returnProperties": true,
    "includedProperties": ["attributes.name", "attributes.price", "attributes.image", "category"]
  }'

Ingestion

Ingest your item catalog, user data, and interaction events. Items are automatically indexed for vector search if a matching embedding template exists.

Interactions Payload

{
  "userId": "user-123",     // optional if sessionId is provided
  "itemId": "prod-001",
  "sessionId": "sess-456",  // optional if userId is provided
  "type": "view",           // view, cart, purchase, click
  "weight": 1,              // optional, default is 1
  "scenarioSlug": "homepage-for-you", // optional, for attribution
  "timestamp": "2024-03-07T12:00:00Z" // optional, default is now
}

Recommendations (Legacy Endpoints)

Specific endpoints for each recommendation logic type. While the unified endpoint is preferred, these individual endpoints provide clear parameter separation.

* Passing `userId` to Item-to-Item, Items-to-Items, or Similar-Products endpoints enables the "Purchase Cap" constraint.

Projection Behavior and Security Rules

Projection runs on raw item document paths and is deterministic across unified and legacy endpoints. Identity fields are preserved for response stability.

• Path strictness is exact: requesting name does not resolve attributes.name.
• Safe but missing paths are omitted from the item payload (no error).
• Unsafe segments (__proto__, constructor, prototype, toString, valueOf) are rejected with HTTP 400.
• When returnProperties=false, includedProperties is ignored and identity-only payload is returned.
• score is passive algorithm metadata and may be absent in lean responses.

Legacy GET Query and HMAC Notes

For signed browser traffic, request placement must match signing scope exactly.

# Signed GET endpoints: projection fields are query params (part of signed URL)
/recommendations/item-to-item/prod-001?scenario=pdp-related&count=8&returnProperties=true&includedProperties=attributes.name,attributes.price

# Signed POST items-to-items: projection fields are body keys (not query keys)
POST /recommendations/items-to-items?scenario=cart-upsell
{
  "itemIds": ["prod-1", "prod-2"],
  "count": 8,
  "returnProperties": true,
  "includedProperties": ["attributes.name", "attributes.price", "attributes.image"]
}

• GET: projection keys must be in query before signing; mismatch causes signature verification failure.
• GET serialization format is CSV in a single query key: includedProperties=a,b,c (not repeated params or bracket notation).
• POST items-to-items: projection keys belong in the JSON body and are signed with the body payload.
• returnProperties on GET should be explicit: use true or false; missing defaults to full payload.
• GET guardrails: at most 20 included paths and total URL length up to 2048 characters; overflow returns HTTP 400.

Projection Path Discovery

Discover valid include paths from raw catalog items, then reuse those exact paths inincludedProperties.

# 1) Fetch a sample item and inspect raw fields
curl "http://localhost:3000/catalog/items?page=1&limit=1" \
  -H "X-Tenant-Id: demo-ecommerce"

# 2) Use literal raw paths from the item JSON
# Valid example: attributes.name
# Invalid alias example: name (unless top-level name actually exists)

Field mapper aliases are independent of projection. A configured mapper path such asfieldMapper.namePath does not make name a valid include path unless that key exists literally at the item top level.

Rollout Validation Checklist

Use this matrix to validate strict-HMAC + projection compatibility end-to-end across engine, SDKs, and widgets.

Suggested Validation Commands

# Engine/API projection checks
cd engine && npm test

# Node SDK projection propagation checks
cd sdks/node && npm test

# Browser SDK projection propagation checks
cd sdks/js-client && npm test

# Widget projection + strict-HMAC smoke checks
cd widgets/carousel && npm run build && npm test
cd widgets/react && npm run build && npm test

Scenarios

Scenarios are named configurations that encapsulate all the logic, filters, and constraints for a specific recommendation placement.

Scenario Schema Example

{
  "name": "Related Products",
  "slug": "pdp-related",
  "logicType": "item-to-item",
  "algorithm": "co-occurrence",
  "filter": "'stock' > 0",
  "boosters": ["boost by 1.2 where 'category' = 'featured'"],
  "constraints": {
    "maxPerCategory": 3,
    "purchasedItemsMaxPercent": 10
  },
  "minItems": 6,
  "maxItems": 12,
  "autoRelaxConstraints": true
}

Segmentations

Segmentations group your catalog into diverse buckets, ensuring that recommendations don't over-represent a single category or brand.

Analytics

Query real-time metrics captured from interactions and impressions. All analytics are powered by ClickHouse for sub-second performance.

Catalog & Infrastructure

Low-level endpoints for catalog inspection, vector search configuration, and identity management.

Tenant Settings PUT Body Example

fieldMapper is optional. Configure it only when your catalog uses non-default paths (for example nested identity/name/image keys). When unset, the engine falls back to top-levelexternalId, category, and raw attributes.

{
  "fieldMapper": {
    "externalIdPath": "attributes.productId",
    "namePath": "attributes.name",
    "categoryPath": "attributes.primaryCategory",
    "coverImagePath": "attributes.images.cover",
    "basePricePath": "attributes.countryPrices.IN",
    "taxonomyPath": "attributes.taxonomyPath"
  },
  "dimensions": [
    { "key": "genre", "type": "enum", "label": "Genre", "facetable": true, "filterable": true, "boostable": true }
  ],
  "freshness": {
    "keyPath": "attributes.releaseDate",
    "type": "date",
    "fallbackToCreatedAt": true
  }
}