Ensemble AI Client API

This API provides AI-powered ensemble (outfit) recommendations based on a given seed product and user context. You can use it to deliver personalized product collections. It supports both production and integration environments, with flexible parameters for style filtering, user history, and fallback recommendations.

URLs

These endpoints return Ensemble AI recommendations for ensembles (outfits/collections) for a given seed product.

Production URL

Use this URL to request ensembles from your production environment.

Copy

https://recs.richrelevance.com/rrserver/api/rrPlatform/ensembleAIRecs

Integration URL

Use this URL to request personalization from your QA, staging or development environment. This allows you to test changes without affecting your production environment.

Copy

https://integration.richrelevance.com/rrserver/api/rrPlatform/ensembleAIRecs

API Input Parameters

Note: Call only the parameters you need. Algonomy operates a set of APIs that support multiple applications and clients concurrently. These APIs may be updated or enhanced by Algonomy at any time.

Note: All parameters are case sensitive.

Name	Required/ Optional	Description
apiClientKey	Required	A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by Algonomy. Example: apiClientKey=b0126f995ac848159d
apiKey	Required	A unique key that identifies the site. Each Algonomy client has a unique API key to separate data and traffic from other clients. This is provided by Algonomy. Example: apiKey=4faeaf752ee40a0f
seed	Conditional Required	If view/purchase history is passed as true, then seed is optional, otherwise it is required. This should be a single product ID. Example: seed= 345234
styleid	Optional	The style id is a unique identifier associated with a style created by Merchandiser in Ensemble AI UI.
includeDisabledStyles	Optional	true (or) false Styles can be enabled or disabled once created. If this parameter is passed as true, then the API will respond with ensembles/outfits for disabled styles as well. If this parameter is not passed (or) passed as false, the outfits will be shown only from the styles that are enabled.
userId	Required when available	User ID. A unique string to identify each customer (user). All customer behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to Algonomy in other applications. Example: userId=0982347
sessionId	Required	Identifies a single visit by a customer. Sessions are used by behavioral models (to scope user behavior in a shopping session) and reporting metrics. Example: sessionId=93484
rcs	Optional	Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response. Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers. Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.
rid	Optional	Region ID. Must be consistent with the ID used in the product region feed. Example: rid=Switzerland-France
useViewsAsSeed	Conditional required	To pass user view history as a seed, pass this flag as true. When this flag is set to true, User Id is required.
usePurchasesAsSeed	Conditional required	To pass user view history as a seed, pass this flag as true. When this flag is set to true, User Id is required.
excludePartialOutfits	Optional	If true, filters out outfits that don’t contain the full number of expected parts.
numParts	Optional	Limits the number of parts in each outfit returned by the API. Useful when only partial outfits (For example 3 out of 6 parts) are needed. If a seed product has only ensembles with 6 parts (products), and numParts = 4, it returns 0 ensembles as it does not have any ensmeble with only 4 parts.
numOfSeeds	Conditional Required (when user history is selected)	Specifies how many products from the user’s history (views or purchases) should be considered as input seeds.
defaultOutfit	Optional	If true, includes a fallback/default outfit recommendation (useful when no strong personalization signal is available).

Sample Requests

To get all ensembles across all styles that are enabled for a given seed product:

Copy

https://recs.richrelevance.com/rrserver/api/rrPlatform/ensembleAIRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454

To get all ensembles for a specific style for a given seed product:

Copy

https://recs.richrelevance.com/rrserver/api/rrPlatform/ensembleAIRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454&styleId=98080934

To get all ensembles across all styles (both enabled & disabled) for a given seed product:

Copy

https://recs.richrelevance.com/rrserver/api/rrPlatform/ensembleAIRecs?apiKey=XXXXXXX&apiClientKey=YYYYY&seed=123423&userId=64545454&styleId=98080934&includeDisabledStyles=true

Sample Response

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 "rcs": "eF5jYilN9khKNE82MzI2001JTDLUNbFIMdRNTks007VMNDNNSjY3MUsyTwQA5M0LJw",
  "recommendedOutfits": [
    {
      "styleId": 1739535644,
      "parts": [
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Fpatagonia-womens-untracked-jacket-skijacke%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=1&p=104-4153&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=1&p=104-4153&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/patagonia-womens-untracked-jacket-skijacke/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_104-4153-0211_pic1_1.jpg",
            "prodName": "Patagonia - Women's Untracked Jacket",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 34998,
            "prodId": "104-4153",
            "brand": "Patagonia"
          },
          "partId": 1
        },
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Fnorroena-womens-lofoten-down800-anorak-skijacke%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=2&p=104-5003&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=2&p=104-5003&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/norroena-womens-lofoten-down800-anorak-skijacke/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_104-5003-0111_pic1_1.jpg",
            "prodName": "Norrøna - Women's Lofoten Down800 Anorak",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 39895,
            "prodId": "104-5003",
            "brand": "Norrøna"
          },
          "partId": 2
        },
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Fortovox-womens-fleece-jacket-fleecejacke%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=3&p=105-3338&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=3&p=105-3338&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/ortovox-womens-fleece-jacket-fleecejacke/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_105-3338-0811_pic1_1.jpg",
            "prodName": "Ortovox - Women's Fleece Jacket",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 15397,
            "prodId": "105-3338",
            "brand": "Ortovox"
          },
          "partId": 3
        },
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Fhestra-alpine-short-gore-tex-5-finger-handschuhe%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=4&p=202-7083&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=4&p=202-7083&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/hestra-alpine-short-gore-tex-5-finger-handschuhe/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_202-7083-0111_pic1_1.jpg",
            "prodName": "Hestra - Alpine Short GORE-TEX 5 Finger",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 4398,
            "prodId": "202-7083",
            "brand": "Hestra"
          },
          "partId": 4
        },
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Fmons-royale-womens-icon-relaxed-tee-merinoshirt%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=5&p=116-8595&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=5&p=116-8595&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/mons-royale-womens-icon-relaxed-tee-merinoshirt/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_116-8595-1311_pic1_1.jpg",
            "prodName": "Mons Royale - Women's Icon Relaxed Tee",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 7196,
            "prodId": "116-8595",
            "brand": "Mons Royale"
          },
          "partId": 5
        },
        {
          "product": {
            "clickUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&ct=https%3A%2F%2Fwww.bergfreunde.de%2Faclima-lightwool-headover-sturmhaube%2F&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=6&p=904-4273&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "salePriceCents": -1,
            "clickTrackingUrl": "https://recs.richrelevance.com/rrserver/apiclick?a=829ecf05023bf578&cak=4b859333a434bf3f&channelId=4b859333a434bf3f&vg=ba7d6236-dab1-48d1-cfa6-9a65bc746b7a&stid=-1&pti=0&pa=-1&pos=6&p=904-4273&styleId=1739535644&srcstr=ensemble_ai&outfit=282433872950%7C345456472895%7C169738309990%7C346378108252%7C216243559662%7C378401646964",
            "prodUrl": "https://www.bergfreunde.de/aclima-lightwool-headover-sturmhaube/",
            "imageUrl": "https://www.bfgcdn.com/out/pictures/generated/product/1/600_600_90/sol_904-4273-0111_pic1_1.jpg",
            "prodName": "Aclima - LightWool Headover",
            "backgroundlessImageUrl": "https://nbi.richrelevance.com/transparency/$SITE_ID$/$ITEM_EXTERNAL_ID$.png",
            "priceCents": 3821,
            "prodId": "904-4273",
            "brand": "Aclima"
          },
          "partId": 6
        }
      ],
      "styleName": "winter"
    },

Sample Response Parameters

Name	Description
rcs	Encoded recommendation context session string.
recommendedOutfits	All the outfits/ensembles recommended for the given seed product
styleid	The style id is a unique identifier associated with a style created by Merchandiser in Ensemble AI UI.
Parts	Returns that number of parts associated with the ensemble/outfit
clickURL	Click URL for the product
salePriceCents	Sale price of the product
clickTrackingURL	Tracking the product click
prodUrl	URL of the product on client website
ImageUrl	URL of the product Image
prodName	Name of the product
priceCents	Price of the product
productid	External Id of the product
Brand	Brand of the product
partId	Which part this product belong to in the outfit. This is based on the style definition and this will be helpful to design appropriate layout for the outfit.
backgroundlessImageUrl	Transparent version of the product image without any background.
styleName	Name of the style theme for the outfit (for exampple "winter").

Tracking Events

When the user clicks on a recommended product from an ensemble, you are required to call a click event tracker for that product before redirecting the user to the product detail page or quick view page. This is to ensure Algonomy can track the click along with the views, so that our products can accurately capture CTR data. This API will expose the following URLs:

productURL is the direct URL to the Product Detail Page. Use this URL to link to the product page, likely as the href attribute of an <a> tag.
clickTrackingURL tracks a product click without redirecting the user to the Product Detail Page. For SEO purposes, you can use this URL together with productURL and trigger a request to clickTrackingURL via a click event listener.
clickURL tracks a product click and redirects the user to the Product Detail Page via an HTTP 301 redirect.

To successfully track clicks, use one of the following options:

Use clickURL which automatically tracks a product click and redirects the user to the Product Detail Page, or
Use productURL as the final URL, and trigger a request to clickTrackingURL via an event listener. This is the suggested approach when SEO optimization is involved.