# Request API

> Current Froomle documentation · [View canonical page](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html)

<a id="_recommendations_api_api_recommendations_get_recommendations"></a>

## POST /{environment}/recommendations/requests

<a id="_description"></a>

### 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.

<a id="_parameters"></a>

### Parameters

| Type | Name | Description | Schema |
| --- | --- | --- | --- |
| **Path** | **environment**<br>_required_ | The environment for which the request is made. | string |
| **Body** | **body**<br>_required_ |  | [RecommendationRequest](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_recommendationrequest) |

<a id="_responses"></a>

### Responses

| HTTP Code | Description | Schema |
| --- | --- | --- |
| **200** | OK | [Recommendations](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_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 |

<a id="_consumes"></a>

### Consumes

-   `application/json`
    

<a id="_produces"></a>

### Produces

-   `application/json`
    

<a id="_example_http_request"></a>

### Example HTTP request

<a id="_request_body"></a>

#### Request body

```json
{
  "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"
}
```

<a id="_example_http_response"></a>

### Example HTTP response

<a id="_response_200"></a>

#### Response 200

```json
{
  "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"
}
```

<a id="_request_description"></a>

## Request Description

<a id="_recommendationrequest"></a>

### RecommendationRequest

Specification of a Recommendation request.

| Name | Description | Schema |
| --- | --- | --- |
| **channel**<br>_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**<br>_optional_ | Unique identifier for the currently displayed item. Required only on article pages. | string |
| **context\_item\_type**<br>_optional_ | Type of the currently displayed item, if applicable. | string |
| **device\_id**<br>_required_ | Unique identifier for a unregistered user (e.g. cookie). Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **histories**<br>_optional_ |  | [Histories](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_histories) |
| **lists**<br>_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](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_requestlist) > array |
| **page\_type**<br>_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**<br>_optional_ | Unique identifier for a logged-in user | string |

<a id="_item"></a>

### Item

One content-item.

| Name | Description | Schema |
| --- | --- | --- |
| **information\_field**<br>_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**<br>_required_ | The identifier of the recommended item | string |
| **rank**<br>_required_ | The item’s position in the complete ranked list. The first item has rank 1. | integer |

<a id="_request_underlying_objects"></a>

### Request underlying objects

<a id="_requestlist"></a>

#### RequestList

The specification to configure which lists of items to retrieve.

| Name | Description | Schema |
| --- | --- | --- |
| **alias**<br>_optional_ | Optional identifier that distinguishes repeated list names within one request. | string |
| **limit**<br>_optional_ | Maximum number of items to return initially. Defaults to list\_size. | integer |
| **list\_content**<br>_optional_ | Candidate items to rerank, or items pinned to a position when rank is provided. | < [ListContentItem](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_listcontentitem) > array |
| **list\_name**<br>_required_ | A string identifier for the list. Repeated names require a distinct alias for each instance. | string |
| **list\_size**<br>_required_ | Maximum number of items to rank for the complete list. | integer |

<a id="_listcontentitem"></a>

#### 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**<br>_required_ | Identifier of the supplied item. | string |
| **item\_type**<br>_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**<br>_optional_ | The rank at which the item should be recommended. Starts counting at 1. If not specified, Froomle will decide the rank. | integer |

<a id="_histories"></a>

#### Histories

Dict of additional customer-defined histories each having a maximum length of 50 tuples

_Type_ : < string, < [HistoryItem](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_historyitem) > array > map

<a id="_historyitem"></a>

#### HistoryItem

Single event entity defined by at least an identifier

| Name | Description | Schema |
| --- | --- | --- |
| **id**<br>_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**<br>_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**<br>_optional_ | True if the entity is allowed to appear in the generated recommendations | boolean |
| **timestamp**<br>_optional_ | Unix timestamp (seconds since Jan 1st 1970 00:00:00) of the event | integer |

<a id="_response_reference"></a>

## Response Reference

<a id="_recommendations"></a>

### Recommendations

| Name | Description | Schema |
| --- | --- | --- |
| **device\_id**<br>_optional_ | Unique identifier for an unregistered user (e.g. cookie). Use the value `"no-consent"` for users that wish to remain anonymous. | string |
| **lists**<br>_optional_ | List of lists of items | < [ResponseList](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_responselist) > array |
| **request\_id**<br>_optional_ | The request identifier as supplied by Froomle. This request\_id needs to be supplied with each logged event. | string |
| **user\_group**<br>_optional_ | The group the user is assigned to. If users get the Froomle experience, this will always be "froomle". | string |
| **user\_id**<br>_optional_ | the user id of the logged-in user | string |

<a id="_responselist"></a>

### 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**<br>_optional_ | Items returned for this page, up to the requested `limit`. Fewer items may be returned when fewer eligible recommendations are available. | < [Item](https://docs.froomle.com/froomle-doc-main/v2/api_reference/recommendations/operations/recommendations_with_env.html#_item) > array |
| **limit**<br>_optional_ | Maximum number of items requested for this page, not the number actually returned. | integer |
| **list\_key**<br>_optional_ | Opaque identifier used to request further pages, when available. | string |
| **list\_name**<br>_optional_ | Bytestring name of the list. As specified in the request. | string |
| **list\_size**<br>_optional_ | Number of items requested for the complete ranked list. This is not a guaranteed count of eligible items. | integer |
| **offset**<br>_optional_ | 1-based rank of the first item in this page, returned by the /lists endpoint. | integer |