Request API Copy page Copy link View Markdown POST /{environment}/recommendations/requests Description Request newly computed recommendations. For each list, the response returns up to limit items from the start of the ranked list, beginning at rank 1. Parameters Type Name Description Schema Path environment required The environment for which the request is made. string Body body required RecommendationRequest Responses HTTP Code Description Schema 200 OK Recommendations 400 The recommendation body was not in the right format, was missing mandatory information or one of the fields (channel, page_type, list_name etc.) has an invalid value. No Content Consumes application/json Produces application/json Example HTTP request Request body { "channel" : "www-desktop", "device_id" : "the-cookie-id-123", "histories" : { "pageviews" : [ { "id" : "electronics", "item_type" : "article", "timestamp" : 1581076041 }, { "id" : "beauty", "item_type" : "article", "timestamp" : 1581054230 }, { "id" : "gaming", "item_type" : "article", "timestamp" : 1581054230 } ] }, "lists" : [ { "limit" : 2, "list_name" : "reco_list_001", "list_size" : 5 } ], "page_type" : "home", "user_id" : "customer-user-id-123" } Example HTTP response Response 200 { "device_id" : "the-cookie-id-123", "lists" : [ { "items" : [ { "information_field" : "some_metadata", "item_id" : "item_id_1", "rank" : 1 }, { "information_field" : "some_metadata", "item_id" : "item_id_2", "rank" : 2 } ], "limit" : 2, "list_key" : "a_unique_list_identifier", "list_name" : "reco_list_001", "list_size" : 5 } ], "request_id" : "2141141", "user_group" : "froomle", "user_id" : "customer-user-id-123" } Request Description RecommendationRequest Specification of a Recommendation request. Name Description Schema channel required The channel used to request the recommendations. Accepted channels are: www, www-desktop, www-mobile, app, app-ios, app-android, app-audio, app-audio-ios and app-audio-android. If none of these fit your use case, please get in touch with your account manager. string context_item optional Unique identifier for the currently displayed item. Required only on article pages. string context_item_type optional Type of the currently displayed item, if applicable. string device_id required Unique identifier for a unregistered user (e.g. cookie). Use the value "no-consent" for users that wish to remain anonymous. string histories optional Histories lists required One or more lists of recommendations to receive. When showing multiple recommendation blocks (e.g. “recommended for you”, “continue reading”, “recent items”) on the same page, include all of them in a single lists array. This ensures that recommendations are generated together, enabling the engine to avoid duplicate items across blocks. < RequestList > array page_type required The page type to request recommendations for. Standard page_types are: home, category, article_detail, product_detail, video_detail, and checkout. If none of these fit your use case, please get in touch with your account manager. string user_id optional Unique identifier for a logged-in user string Item One content-item. Name Description Schema information_field optional The Froomle API can be configured to return additional information fields (if present in the item information). Please contact the Froomle support team to set this up. string item_id required The identifier of the recommended item string rank required The item’s position in the complete ranked list. The first item has rank 1. integer Request underlying objects RequestList The specification to configure which lists of items to retrieve. Name Description Schema alias optional Optional identifier that distinguishes repeated list names within one request. string limit optional Maximum number of items to return initially. Defaults to list_size. integer list_content optional Candidate items to rerank, or items pinned to a position when rank is provided. < ListContentItem > array list_name required A string identifier for the list. Repeated names require a distinct alias for each instance. string list_size required Maximum number of items to rank for the complete list. integer ListContentItem One supplied candidate or fixed-rank item. If used in a request with more than one list, use exclusions as needed to avoid repeats across lists. Name Description Schema id required Identifier of the supplied item. string item_type optional Type of the entity (e.g. item, article, video, category, group, …). These types are Froomle-defined, please consult your solutions architect for the correct type. string rank optional The rank at which the item should be recommended. Starts counting at 1. If not specified, Froomle will decide the rank. integer Histories Dict of additional customer-defined histories each having a maximum length of 50 tuples Type : < string, < HistoryItem > array > map HistoryItem Single event entity defined by at least an identifier Name Description Schema id required Identifier of the entity of the event, we support most entities that would appear in a detail_pageview or item_interaction. string item_type optional Type of the entity (e.g. item, article, video, category, group, …). These types are Froomle-defined, please consult your solutions architect for the correct type. string reconsumable optional True if the entity is allowed to appear in the generated recommendations boolean timestamp optional Unix timestamp (seconds since Jan 1st 1970 00:00:00) of the event integer Response Reference Recommendations Name Description Schema device_id optional Unique identifier for an unregistered user (e.g. cookie). Use the value "no-consent" for users that wish to remain anonymous. string lists optional List of lists of items < ResponseList > array request_id optional The request identifier as supplied by Froomle. This request_id needs to be supplied with each logged event. string user_group optional The group the user is assigned to. If users get the Froomle experience, this will always be "froomle". string user_id optional the user id of the logged-in user string ResponseList Contains up to limit items from a ranked list requested with list_size. If a list_key is available, further pages can be requested from the /lists endpoint. Name Description Schema items optional Items returned for this page, up to the requested limit. Fewer items may be returned when fewer eligible recommendations are available. < Item > array limit optional Maximum number of items requested for this page, not the number actually returned. integer list_key optional Opaque identifier used to request further pages, when available. string list_name optional Bytestring name of the list. As specified in the request. string list_size optional Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. integer offset optional 1-based rank of the first item in this page, returned by the /lists endpoint. integer