# API Reference
> Source: https://docs.recombee.com/api

# API Reference

This section lists all the available API endpoints, that allow you to manage item catalog, users, their interactions and get recommendations.

* Version: `6.3.0`
* Base URL: Based on the [region](/regions) of your database
* API consumes: `application/json`
* API produces: `application/json`
* Authentication: [HMAC](/authentication) (already implemented in the SDKs)
* OpenAPI definition: [YAML](/openapi.yaml) | [JSON](/openapi.json)

## Items

The following methods allow you to maintain the set of items in the catalog. The items are specified using their ids, which are unique string identifiers matching _^\[a-zA-Z0-9\_-:@.\]+$_, i.e., they may consist of digits, Latin letters, underscores, colons, minus signs, at signs, and dots. Item ID `undefined` is forbidden.

put

#### Add Item

Adds new item of the given `itemId` to the items catalog.

All the item properties for the newly created items are set to null.

```js
client.send(new requests.AddItem(itemId));
```

```python
client.send(AddItem(item_id))
```

```ruby
client.send(AddItem.new(item_id))
```

```java
client.send(new AddItem(itemId));
```

```php
$client->send(new Reqs\AddItem($item_id));
```

```csharp
client.Send(new AddItem(itemId));
```

```go
request := client.NewAddItem(itemId)

_, err := request.Send()
```

```http
PUT /{databaseId}/items/{itemId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item to be created.

---

##### Responses

201

Successful operation.

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

409

The `itemId` is already present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Item

Deletes an item of the given `itemId` from the catalog.

If there are any _purchases_, _ratings_, _bookmarks_, _cart additions_, or _detail views_ of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some _series_, it will be removed from all the _series_ where present.

If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely.

```js
client.send(new requests.DeleteItem(itemId));
```

```python
client.send(DeleteItem(item_id))
```

```ruby
client.send(DeleteItem.new(item_id))
```

```java
client.send(new DeleteItem(itemId));
```

```php
$client->send(new Reqs\DeleteItem($item_id));
```

```csharp
client.Send(new DeleteItem(itemId));
```

```go
request := client.NewDeleteItem(itemId)

_, err := request.Send()
```

```http
DELETE /{databaseId}/items/{itemId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item to be deleted.

---

##### Responses

200

Successful operation.

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

The `itemId` is not present in the item catalog. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Items

Gets a list of IDs of items currently present in the catalog.

```js
const result = await client.send(new requests.ListItems({
  // optional parameters:
  filter: 'price > 50',                                   // string
  count: 10,                                              // integer
  offset: 0,                                              // integer
  returnProperties: true,                                 // boolean
  includedProperties: ['title', 'price', 'publishedAt'],  // array
}));
```

```python
result = client.send(ListItems(
    # optional parameters:
    filter='price > 50',                                    # string
    count=10,                                               # integer
    offset=0,                                               # integer
    return_properties=True,                                 # boolean
    included_properties=['title', 'price', 'publishedAt'],  # array
))
```

```ruby
result = client.send(ListItems.new({
  # optional parameters:
  filter: 'price > 50',                                    # string
  count: 10,                                               # integer
  offset: 0,                                               # integer
  return_properties: true,                                 # boolean
  included_properties: ['title', 'price', 'publishedAt'],  # array
}))
```

```java
Item[] result = client.send(new ListItems()
    .setFilter("price > 50")                                               // String
    .setCount(10)                                                          // long
    .setOffset(0)                                                          // long
    .setReturnProperties(true)                                             // boolean
    .setIncludedProperties(new String[]{"title", "price", "publishedAt"})  // String[]
);
```

```php
$result = $client->send(new Reqs\ListItems([
    // optional parameters:
    'filter' => 'price > 50',                                   // string
    'count' => 10,                                              // integer
    'offset' => 0,                                              // integer
    'returnProperties' => true,                                 // boolean
    'includedProperties' => ['title', 'price', 'publishedAt'],  // array
]));
```

```csharp
IEnumerable<Item> result = client.Send(new ListItems(
    // optional parameters:
    filter: "price > 50",                                                 // string
    count: 10,                                                            // long
    offset: 0,                                                            // long
    returnProperties: true,                                               // bool
    includedProperties: new string[] { "title", "price", "publishedAt" }  // string[]
));
```

```go
request := client.NewListItems().
    // optional parameters:
    SetFilter("price > 50").                                          // string
    SetCount(10).                                                     // int
    SetOffset(0).                                                     // int
    SetReturnProperties(true).                                        // bool
    SetIncludedProperties([]string{"title", "price", "publishedAt"})  // []string

result, err := request.Send() // result is of the type []bindings.Item
```

```http
GET /{databaseId}/items/list/?filter=price > 50
&count=10
&offset=0
&returnProperties=true
&includedProperties=title,price,publishedAt
```

---

Calls Limit Per Minute

100

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

filter

String

Located in: **query**

Required: **No**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter items to be listed. Only the items for which the expression is _true_ will be returned.

---

count

Integer

Located in: **query**

Required: **No**

The number of items to be listed.

---

offset

Integer

Located in: **query**

Required: **No**

Specifies the number of items to skip (ordered by `itemId`).

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **1.4.0**

With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary.

Example response:

```
  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "categories":   ["Electronics", "Televisions"],
      "price": 342,
      "url": "myshop.com/tv-178"
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "categories":   ["Home & Kitchen"],
      "price": 39,
      "url": "myshop.com/mixer-42"
    }
  ]
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **1.4.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  [
    {
      "itemId": "tv-178",
      "description": "4K TV with 3D feature",
      "price": 342
    },
    {
      "itemId": "mixer-42",
      "description": "Stainless Steel Mixer",
      "price": 39
    }
  ]
```

---

##### Responses

200

Successful operation.

```
[
  "item-1",
  "item-2",
  "item-3"
]
```

---

404

If present, `filter` contains a non-existing item property.

---

delete

#### Delete More Items

Deletes all the items that pass the filter.

If an item becomes obsolete/no longer available, it is meaningful to **keep it in the catalog** (along with all the interaction data, which are very useful) and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely.

```js
const result = await client.send(new requests.DeleteMoreItems(filter));
```

```python
result = client.send(DeleteMoreItems(filter))
```

```ruby
result = client.send(DeleteMoreItems.new(filter))
```

```java
DeleteMoreItemsResponse result = client.send(new DeleteMoreItems(filter));
```

```php
$result = $client->send(new Reqs\DeleteMoreItems($filter));
```

```csharp
DeleteMoreItemsResponse result = client.Send(new DeleteMoreItems(filter));
```

```go
request := client.NewDeleteMoreItems(filter)

result, err := request.Send() // result is of the type bindings.DeleteMoreItemsResponse
```

```http
DELETE /{databaseId}/more-items/
Body (application/json):
{
  "filter": "price > 50"
}
```

---

Since version

3.3.0

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.3.0**

ID of your database.

---

filter

String

Located in: **body**

Required: **Yes**

Since version: **3.3.0**

A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated.

---

##### Responses

200

Successful operation.

```
{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}
```

---

400

Invalid filter.

---

## Item Properties

### Item properties definition

Item properties are used for modeling your domain. The following methods allow the definition of item properties. The properties may be thought of as columns in a relational database table.

put

#### Add Item Property

Adding an item property is somewhat equivalent to adding a column to the table of items. The items may be characterized by various properties of different types.

```js
client.send(new requests.AddItemProperty(propertyName, type, {
  // optional parameters:
  role: 'title',  // string / Object
  metadata: [],   // array
}));
```

```python
client.send(AddItemProperty(property_name, type,
    # optional parameters:
    role='title',  # string / dict
    metadata=[],   # array
))
```

```ruby
client.send(AddItemProperty.new(property_name, type, {
  # optional parameters:
  role: 'title',  # string / Hash
  metadata: [],   # array
}))
```

```java
client.send(new AddItemProperty(propertyName, type)
    .setRole(new PropertyRole("title"))     // PropertyRole
    .setMetadata(new PropertyMetadata[]{})  // PropertyMetadata[]
);
```

```php
$client->send(new Reqs\AddItemProperty($property_name, $type, [
    // optional parameters:
    'role' => 'title',  // string / array (map)
    'metadata' => [],   // array
]));
```

```csharp
client.Send(new AddItemProperty(propertyName, type,
    // optional parameters:
    role: new PropertyRole(name: "title"),  // PropertyRole
    metadata: new PropertyMetadata[] {}     // PropertyMetadata[]
));
```

```go
request := client.NewAddItemProperty(propertyName, propertyType).
    // optional parameters:
    SetRole(bindings.PropertyRole{Name: "title"}).  // bindings.PropertyRole
    SetMetadata([]bindings.PropertyMetadata{})      // []bindings.PropertyMetadata

_, err := request.Send()
```

```http
PUT /{databaseId}/items/properties/{propertyName}
Body (application/json):
{
  "type": "string",
  "role": "title",
  "metadata": []
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Name of the item property to be created. Currently, the following names are reserved: `id`, `itemid`, case-insensitively. Also, the length of the property name must not exceed 63 characters.

---

type

String

Located in: **body**

Required: **Yes**

Value type of the item property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`, `image` or `imageList`.

* `int` \- Signed integer number.
* `double` \- Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
* `string` \- UTF-8 string.
* `boolean` \- _true_ / _false_
* `timestamp` \- Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
* `set` \- Set of strings.
* `image` \- URL of an image (`jpeg`, `png` or `gif`).
* `imageList` \- List of URLs that refer to images.

---

role

String

Object

Located in: **body**

Required: **No**

Since version: **6.3.0**

[Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.

---

metadata

Array

Located in: **body**

Required: **No**

Since version: **6.3.0**

List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.

---

##### Responses

201

Successful operation.

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$, or it is a reserved keyword (''id'', ''itemid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.

---

409

Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Item Property

Deleting an item property is roughly equivalent to removing a column from the table of items.

```js
client.send(new requests.DeleteItemProperty(propertyName));
```

```python
client.send(DeleteItemProperty(property_name))
```

```ruby
client.send(DeleteItemProperty.new(property_name))
```

```java
client.send(new DeleteItemProperty(propertyName));
```

```php
$client->send(new Reqs\DeleteItemProperty($property_name));
```

```csharp
client.Send(new DeleteItemProperty(propertyName));
```

```go
request := client.NewDeleteItemProperty(propertyName)

_, err := request.Send()
```

```http
DELETE /{databaseId}/items/properties/{propertyName}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Name of the property to be deleted.

---

##### Responses

200

Successful operation.

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$.

---

404

Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the item property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Get Item Property Info

Gets information about specified item property.

```js
const result = await client.send(new requests.GetItemPropertyInfo(propertyName));
```

```python
result = client.send(GetItemPropertyInfo(property_name))
```

```ruby
result = client.send(GetItemPropertyInfo.new(property_name))
```

```java
PropertyInfo result = client.send(new GetItemPropertyInfo(propertyName));
```

```php
$result = $client->send(new Reqs\GetItemPropertyInfo($property_name));
```

```csharp
PropertyInfo result = client.Send(new GetItemPropertyInfo(propertyName));
```

```go
request := client.NewGetItemPropertyInfo(propertyName)

result, err := request.Send() // result is of the type bindings.PropertyInfo
```

```http
GET /{databaseId}/items/properties/{propertyName}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Name of the property about which the information is to be retrieved.

---

##### Responses

200

Successful operation.

```
{
  "name": "num-processors",
  "type": "int"
}
```

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$.

---

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Properties

Gets the list of all the item properties in your database.

```js
const result = await client.send(new requests.ListItemProperties());
```

```python
result = client.send(ListItemProperties())
```

```ruby
result = client.send(ListItemProperties.new())
```

```java
PropertyInfo[] result = client.send(new ListItemProperties());
```

```php
$result = $client->send(new Reqs\ListItemProperties());
```

```csharp
IEnumerable<PropertyInfo> result = client.Send(new ListItemProperties());
```

```go
request := client.NewListItemProperties()

result, err := request.Send() // result is of the type []bindings.PropertyInfo
```

```http
GET /{databaseId}/items/properties/list/
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

##### Responses

200

Successful operation.

```
[
  {
    "name": "tags",
    "type": "set"
  },
  {
    "name": "release-date",
    "type": "timestamp"
  },
  {
    "name": "description",
    "type": "string"
  }
]
```

---

404

Invalid URL.

---

### Values of item properties

The following methods allow assigning property values to items in the catalog. Set values are examined by content-based algorithms and used for recommendations, especially in the case of cold-start items that have no interactions yet. Properties are also used in [ReQL](https://docs.recombee.com/reql) for filtering and boosting according to your business rules.

post

#### Set Item Values

Sets/updates (some) property values of the given item. The properties (columns) must be previously created by [Add item property](https://docs.recombee.com/api#add-item-property).

```js
client.send(new requests.SetItemValues(itemId, values, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```python
client.send(SetItemValues(item_id, values,
    # optional parameters:
    cascade_create=True,  # boolean
))
```

```ruby
client.send(SetItemValues.new(item_id, values, {
  # optional parameters:
  cascade_create: true,  # boolean
}))
```

```java
client.send(new SetItemValues(itemId, values)
    .setCascadeCreate(true)  // boolean
);
```

```php
$client->send(new Reqs\SetItemValues($item_id, $values, [
    // optional parameters:
    'cascadeCreate' => true,  // boolean
]));
```

```csharp
client.Send(new SetItemValues(itemId, values,
    // optional parameters:
    cascadeCreate: true  // bool
));
```

```go
request := client.NewSetItemValues(itemId, values).
    // optional parameters:
    SetCascadeCreate(true)  // bool

_, err := request.Send()
```

```http
POST /{databaseId}/items/{itemId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item which will be modified.

---

Object

Located in: **body**

Required: **Yes**

The values for the individual properties.

Example of the body:

```
  {
    "product_description": "4K TV with 3D feature",
    "categories":   ["Electronics", "Televisions"],
    "price_usd": 342,
    "in_stock_from": "2016-11-16T08:00Z",
    "image": "http://myexamplesite.com/products/4ktelevision3d/image.jpg",
    "other_images": ["http://myexamplesite.com/products/4ktelevision3d/image2.jpg",
                     "http://myexamplesite.com/products/4ktelevision3d/image3.jpg"]
  }
```

Set item values can also **cascade create** the item if it's not already present in the database.

For this functionality:

* _When using the client libraries_: Set the optional _cascadeCreate_ parameter to true, just like when creating an interaction.
* _When using directly REST API_: Set special "property" `!cascadeCreate`.  
Example:  
```  
  {  
    "product_description": "4K TV with 3D feature",  
    "!cascadeCreate": true  
  }  
```  
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

---

##### Responses

200

Successful operation.

---

400

Property name does not match ''^\[a-zA-Z0-9\_-:\]+$'', value does not match the property type.

---

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Get Item Values

Gets all the current property values of the given item.

```js
const result = await client.send(new requests.GetItemValues(itemId));
```

```python
result = client.send(GetItemValues(item_id))
```

```ruby
result = client.send(GetItemValues.new(item_id))
```

```java
Map<String, Object> result = client.send(new GetItemValues(itemId));
```

```php
$result = $client->send(new Reqs\GetItemValues($item_id));
```

```csharp
Item result = client.Send(new GetItemValues(itemId));
```

```go
request := client.NewGetItemValues(itemId)

result, err := request.Send() // result is of the type map[string]interface{}
```

```http
GET /{databaseId}/items/{itemId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose properties are to be obtained.

---

##### Responses

200

Successful operation.

```
{
  "release-date": null,
  "tags": [
    "electronics",
    "laptops"
  ],
  "num-processors": 12,
  "description": "Very powerful laptop",
  "weight": 1.6
}
```

---

400

The _itemId_ does not match ^\[a-zA-Z0-9\_-:@.\]+$

---

404

Item of the given _itemId_ is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.

---

post

#### Update More Items

Updates (some) property values of all the items that pass the filter.

Example: _Setting all the items that are older than a week as unavailable_

```
  {
    "filter": "'releaseDate' < now() - 7*24*3600",
    "changes": {"available": false}
  }
```

```js
const result = await client.send(new requests.UpdateMoreItems(filter, changes));
```

```python
result = client.send(UpdateMoreItems(filter, changes))
```

```ruby
result = client.send(UpdateMoreItems.new(filter, changes))
```

```java
UpdateMoreItemsResponse result = client.send(new UpdateMoreItems(filter, changes));
```

```php
$result = $client->send(new Reqs\UpdateMoreItems($filter, $changes));
```

```csharp
UpdateMoreItemsResponse result = client.Send(new UpdateMoreItems(filter, changes));
```

```go
request := client.NewUpdateMoreItems(filter, changes)

result, err := request.Send() // result is of the type bindings.UpdateMoreItemsResponse
```

```http
POST /{databaseId}/more-items/
Body (application/json):
{
  "filter": "price > 50",
  "changes": {}
}
```

---

Since version

3.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.3.0**

ID of your database.

---

filter

String

Located in: **body**

Required: **Yes**

Since version: **3.3.0**

A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated.

---

changes

Object

Located in: **body**

Required: **Yes**

Since version: **3.3.0**

A dictionary where the keys are properties that shall be updated.

---

##### Responses

200

Successful operation. Returns IDs of updated items and their count.

```
{
  "itemIds": [
    "item-42",
    "item-125",
    "item-11"
  ],
  "count": 3
}
```

---

400

Invalid filter, property name does not match ''^\[a-zA-Z0-9\_-:\]+$'', value does not match the property type.

---

404

Property of the given name is not present in the database.

---

## Users

The following methods allow you to manage users in your database. User ID `undefined` is forbidden.

put

#### Add User

Adds a new user to the database.

```js
client.send(new requests.AddUser(userId));
```

```python
client.send(AddUser(user_id))
```

```ruby
client.send(AddUser.new(user_id))
```

```java
client.send(new AddUser(userId));
```

```php
$client->send(new Reqs\AddUser($user_id));
```

```csharp
client.Send(new AddUser(userId));
```

```go
request := client.NewAddUser(userId)

_, err := request.Send()
```

```http
PUT /{databaseId}/users/{userId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user to be added.

---

##### Responses

201

Successful operation.

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

409

User of the given userId is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete User

Deletes a user of the given _userId_ from the database.

If there are any purchases, ratings, bookmarks, cart additions or detail views made by the user present in the database, they will be deleted in cascade as well.

```js
client.send(new requests.DeleteUser(userId));
```

```python
client.send(DeleteUser(user_id))
```

```ruby
client.send(DeleteUser.new(user_id))
```

```java
client.send(new DeleteUser(userId));
```

```php
$client->send(new Reqs\DeleteUser($user_id));
```

```csharp
client.Send(new DeleteUser(userId));
```

```go
request := client.NewDeleteUser(userId)

_, err := request.Send()
```

```http
DELETE /{databaseId}/users/{userId}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user to be deleted.

---

##### Responses

200

Successful operation.

---

400

The _userId_ does not match ''^\[a-zA-Z0-9\_-:@.\]+$''.

---

404

User of the given `userId` is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

put

#### Merge Users

Allowed on Client-Side

Merges interactions (purchases, ratings, bookmarks, detail views ...) of two different users under a single user ID. This is especially useful for online e-commerce applications working with anonymous users identified by unique tokens such as the session ID. In such applications, it may often happen that a user owns a persistent account, yet accesses the system anonymously while, e.g., putting items into a shopping cart. At some point in time, such as when the user wishes to confirm the purchase, (s)he logs into the system using his/her username and password. The interactions made under anonymous session ID then become connected with the persistent account, and merging these two becomes desirable.

Merging happens between two users referred to as the _target_ and the _source_. After the merge, all the interactions of the source user are attributed to the target user, and the source user is **deleted**.

By default, the _Merge Users_ request is only available from server-side integrations for security reasons, to prevent potential abuse. If you need to call this request from a client-side environment (such as a web or mobile app), please contact our support and request access to enable this feature for your database.

```js
client.send(new recombee.MergeUsers(targetUserId, sourceUserId, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```kotlin
client.send(MergeUsers(targetUserId, sourceUserId,
    // optional parameters:
    cascadeCreate = true,  // Boolean
))
```

```swift
_ = try await client.send(MergeUsers(targetUserId: targetUserId, sourceUserId: sourceUserId,
    // optional parameters:
    cascadeCreate: true  // Bool
))
```

```js
client.send(new requests.MergeUsers(targetUserId, sourceUserId, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```python
client.send(MergeUsers(target_user_id, source_user_id,
    # optional parameters:
    cascade_create=True,  # boolean
))
```

```ruby
client.send(MergeUsers.new(target_user_id, source_user_id, {
  # optional parameters:
  cascade_create: true,  # boolean
}))
```

```java
client.send(new MergeUsers(targetUserId, sourceUserId)
    .setCascadeCreate(true)  // boolean
);
```

```php
$client->send(new Reqs\MergeUsers($target_user_id, $source_user_id, [
    // optional parameters:
    'cascadeCreate' => true,  // boolean
]));
```

```csharp
client.Send(new MergeUsers(targetUserId, sourceUserId,
    // optional parameters:
    cascadeCreate: true  // bool
));
```

```go
request := client.NewMergeUsers(targetUserId, sourceUserId).
    // optional parameters:
    SetCascadeCreate(true)  // bool

_, err := request.Send()
```

```http
PUT /{databaseId}/users/{targetUserId}/merge/{sourceUserId}?cascadeCreate=true
```

---

Calls Limit Per Minute

100

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

targetUserId

String

Located in: **path**

Required: **Yes**

ID of the target user.

---

sourceUserId

String

Located in: **path**

Required: **Yes**

ID of the source user.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Sets whether the user _targetUserId_ should be created if not present in the database.

---

##### Responses

201

Successful operation.

---

400

The _sourceUserId_ or _targetUserId_ does not match ^\[a-zA-Z0-9\_-:@.\]+$

---

404

The _sourceUserId_ or _targetUserId_ does not exist in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Users

Gets a list of IDs of users currently present in the catalog.

```js
const result = await client.send(new requests.ListUsers({
  // optional parameters:
  filter: '\'country\' == "US"',                // string
  count: 10,                                    // integer
  offset: 0,                                    // integer
  returnProperties: true,                       // boolean
  includedProperties: ['username', 'country'],  // array
}));
```

```python
result = client.send(ListUsers(
    # optional parameters:
    filter='\'country\' == "US"',                 # string
    count=10,                                     # integer
    offset=0,                                     # integer
    return_properties=True,                       # boolean
    included_properties=['username', 'country'],  # array
))
```

```ruby
result = client.send(ListUsers.new({
  # optional parameters:
  filter: '\'country\' == "US"',                 # string
  count: 10,                                     # integer
  offset: 0,                                     # integer
  return_properties: true,                       # boolean
  included_properties: ['username', 'country'],  # array
}))
```

```java
User[] result = client.send(new ListUsers()
    .setFilter("'country' == \"US\"")                            // String
    .setCount(10)                                                // long
    .setOffset(0)                                                // long
    .setReturnProperties(true)                                   // boolean
    .setIncludedProperties(new String[]{"username", "country"})  // String[]
);
```

```php
$result = $client->send(new Reqs\ListUsers([
    // optional parameters:
    'filter' => '\'country\' == "US"',                // string
    'count' => 10,                                    // integer
    'offset' => 0,                                    // integer
    'returnProperties' => true,                       // boolean
    'includedProperties' => ['username', 'country'],  // array
]));
```

```csharp
IEnumerable<User> result = client.Send(new ListUsers(
    // optional parameters:
    filter: "'country' == \"US\"",                              // string
    count: 10,                                                  // long
    offset: 0,                                                  // long
    returnProperties: true,                                     // bool
    includedProperties: new string[] { "username", "country" }  // string[]
));
```

```go
request := client.NewListUsers().
    // optional parameters:
    SetFilter("'country' == \"US\"").                       // string
    SetCount(10).                                           // int
    SetOffset(0).                                           // int
    SetReturnProperties(true).                              // bool
    SetIncludedProperties([]string{"username", "country"})  // []string

result, err := request.Send() // result is of the type []bindings.User
```

```http
GET /{databaseId}/users/list/?filter='country' == "US"
&count=10
&offset=0
&returnProperties=true
&includedProperties=username,country
```

---

Calls Limit Per Minute

100

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

filter

String

Located in: **query**

Required: **No**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter users to be listed. Only the users for which the expression is _true_ will be returned.

---

count

Integer

Located in: **query**

Required: **No**

The number of users to be listed.

---

offset

Integer

Located in: **query**

Required: **No**

Specifies the number of users to skip (ordered by `userId`).

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **1.4.0**

With `returnProperties=true`, property values of the listed users are returned along with their IDs in a JSON dictionary.

Example response:

```
  [
    {
      "userId": "user-81",
      "country": "US",
      "sex": "M"
    },
    {
      "userId": "user-314",
      "country": "CAN",
      "sex": "F"
    }
  ]
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **1.4.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=country`:

```
  [
    {
      "userId": "user-81",
      "country": "US"
    },
    {
      "userId": "user-314",
      "country": "CAN"
    }
  ]
```

---

##### Responses

200

Successful operation.

```
[
  "user-1",
  "user-2",
  "user-3"
]
```

---

404

Invalid URL.

---

## User Properties

### User properties definition

User properties are used for modeling users. The following methods allow the definition of user properties. The properties may be thought of as columns in a relational database table.

put

#### Add User Property

Adding a user property is somewhat equivalent to adding a column to the table of users. The users may be characterized by various properties of different types.

```js
client.send(new requests.AddUserProperty(propertyName, type, {
  // optional parameters:
  role: 'title',  // string / Object
  metadata: [],   // array
}));
```

```python
client.send(AddUserProperty(property_name, type,
    # optional parameters:
    role='title',  # string / dict
    metadata=[],   # array
))
```

```ruby
client.send(AddUserProperty.new(property_name, type, {
  # optional parameters:
  role: 'title',  # string / Hash
  metadata: [],   # array
}))
```

```java
client.send(new AddUserProperty(propertyName, type)
    .setRole(new PropertyRole("title"))     // PropertyRole
    .setMetadata(new PropertyMetadata[]{})  // PropertyMetadata[]
);
```

```php
$client->send(new Reqs\AddUserProperty($property_name, $type, [
    // optional parameters:
    'role' => 'title',  // string / array (map)
    'metadata' => [],   // array
]));
```

```csharp
client.Send(new AddUserProperty(propertyName, type,
    // optional parameters:
    role: new PropertyRole(name: "title"),  // PropertyRole
    metadata: new PropertyMetadata[] {}     // PropertyMetadata[]
));
```

```go
request := client.NewAddUserProperty(propertyName, propertyType).
    // optional parameters:
    SetRole(bindings.PropertyRole{Name: "title"}).  // bindings.PropertyRole
    SetMetadata([]bindings.PropertyMetadata{})      // []bindings.PropertyMetadata

_, err := request.Send()
```

```http
PUT /{databaseId}/users/properties/{propertyName}
Body (application/json):
{
  "type": "string",
  "role": "title",
  "metadata": []
}
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

Name of the user property to be created. Currently, the following names are reserved: `id`, `userid`, case-insensitively. Also, the length of the property name must not exceed 63 characters.

---

type

String

Located in: **body**

Required: **Yes**

Value type of the user property to be created. One of: `int`, `double`, `string`, `boolean`, `timestamp`, `set`.

* `int` \- Signed integer number.
* `double` \- Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).
* `string` \- UTF-8 string.
* `boolean` \- _true_ / _false_
* `timestamp` \- Value representing date and time. ISO8601-1 pattern (string) or UTC epoch time (number).
* `set` \- Set of strings.

---

role

String

Object

Located in: **body**

Required: **No**

[Role](https://docs.recombee.com/api/property_roles_metadata#roles) to assign to the property.

---

metadata

Array

Located in: **body**

Required: **No**

List of [metadata](https://docs.recombee.com/api/property_roles_metadata#metadata) entries to assign to the property.

---

##### Responses

201

Successful operation.

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$, or it is a reserved keyword (''id'', ''userid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid.

---

409

Property of the given name is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete User Property

Deleting a user property is roughly equivalent to removing a column from the table of users.

```js
client.send(new requests.DeleteUserProperty(propertyName));
```

```python
client.send(DeleteUserProperty(property_name))
```

```ruby
client.send(DeleteUserProperty.new(property_name))
```

```java
client.send(new DeleteUserProperty(propertyName));
```

```php
$client->send(new Reqs\DeleteUserProperty($property_name));
```

```csharp
client.Send(new DeleteUserProperty(propertyName));
```

```go
request := client.NewDeleteUserProperty(propertyName)

_, err := request.Send()
```

```http
DELETE /{databaseId}/users/properties/{propertyName}
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

Name of the property to be deleted.

---

##### Responses

200

Successful operation.

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$.

---

404

Property of the given name is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the user property was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Get User Property Info

Gets information about specified user property.

```js
const result = await client.send(new requests.GetUserPropertyInfo(propertyName));
```

```python
result = client.send(GetUserPropertyInfo(property_name))
```

```ruby
result = client.send(GetUserPropertyInfo.new(property_name))
```

```java
PropertyInfo result = client.send(new GetUserPropertyInfo(propertyName));
```

```php
$result = $client->send(new Reqs\GetUserPropertyInfo($property_name));
```

```csharp
PropertyInfo result = client.Send(new GetUserPropertyInfo(propertyName));
```

```go
request := client.NewGetUserPropertyInfo(propertyName)

result, err := request.Send() // result is of the type bindings.PropertyInfo
```

```http
GET /{databaseId}/users/properties/{propertyName}
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

propertyName

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

Name of the property about which the information is to be retrieved.

---

##### Responses

200

Successful operation.

```
{
  "name": "country",
  "type": "string"
}
```

---

400

Property name does not match ^\[a-zA-Z0-9\_-:\]+$.

---

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Properties

Gets the list of all the user properties in your database.

```js
const result = await client.send(new requests.ListUserProperties());
```

```python
result = client.send(ListUserProperties())
```

```ruby
result = client.send(ListUserProperties.new())
```

```java
PropertyInfo[] result = client.send(new ListUserProperties());
```

```php
$result = $client->send(new Reqs\ListUserProperties());
```

```csharp
IEnumerable<PropertyInfo> result = client.Send(new ListUserProperties());
```

```go
request := client.NewListUserProperties()

result, err := request.Send() // result is of the type []bindings.PropertyInfo
```

```http
GET /{databaseId}/users/properties/list/
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

##### Responses

200

Successful operation.

```
[
  {
    "name": "country",
    "type": "string"
  },
  {
    "name": "sex",
    "type": "string"
  }
]
```

---

404

Invalid URL.

---

### Values of user properties

The following methods allow assigning property values to the user. Set values are examined by content-based algorithms and used in building recommendations, especially for users that have only a few interactions (e.g., new users). Useful properties may be, for example, gender or region. The values can be used in filtering using the [context\_user ReQL function](https://docs.recombee.com/reql_functions#context-user-function).

post

#### Set User Values

Sets/updates (some) property values of the given user. The properties (columns) must be previously created by [Add user property](https://docs.recombee.com/api#add-user-property).

```js
client.send(new requests.SetUserValues(userId, values, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```python
client.send(SetUserValues(user_id, values,
    # optional parameters:
    cascade_create=True,  # boolean
))
```

```ruby
client.send(SetUserValues.new(user_id, values, {
  # optional parameters:
  cascade_create: true,  # boolean
}))
```

```java
client.send(new SetUserValues(userId, values)
    .setCascadeCreate(true)  // boolean
);
```

```php
$client->send(new Reqs\SetUserValues($user_id, $values, [
    // optional parameters:
    'cascadeCreate' => true,  // boolean
]));
```

```csharp
client.Send(new SetUserValues(userId, values,
    // optional parameters:
    cascadeCreate: true  // bool
));
```

```go
request := client.NewSetUserValues(userId, values).
    // optional parameters:
    SetCascadeCreate(true)  // bool

_, err := request.Send()
```

```http
POST /{databaseId}/users/{userId}
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of the user which will be modified.

---

Object

Located in: **body**

Required: **Yes**

Since version: **1.3.0**

The values for the individual properties.

Example of the body:

```
  {
    "country": "US",
    "sex": "F"
  }
```

Set user values can also **cascade create** the user if it's not already present in the database.

For this functionality:

* _When using the client libraries_: Set the optional _cascadeCreate_ parameter to true, just like when creating an interaction.
* _When using directly REST API_: Set special "property" `!cascadeCreate`.  
Example:  
```  
  {  
    "country": "US",  
    "!cascadeCreate": true  
  }  
```  
Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.

---

##### Responses

200

Successful operation.

---

400

Property name does not match ''^\[a-zA-Z0-9\_-:\]+$'', value does not agree to property type.

---

404

Property of the given name is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Get User Values

Gets all the current property values of the given user.

```js
const result = await client.send(new requests.GetUserValues(userId));
```

```python
result = client.send(GetUserValues(user_id))
```

```ruby
result = client.send(GetUserValues.new(user_id))
```

```java
Map<String, Object> result = client.send(new GetUserValues(userId));
```

```php
$result = $client->send(new Reqs\GetUserValues($user_id));
```

```csharp
User result = client.Send(new GetUserValues(userId));
```

```go
request := client.NewGetUserValues(userId)

result, err := request.Send() // result is of the type map[string]interface{}
```

```http
GET /{databaseId}/users/{userId}
```

---

Since version

1.3.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **1.3.0**

ID of the user whose properties are to be obtained.

---

##### Responses

200

Successful operation.

```
{
  "country": "US",
  "sex": "F"
}
```

---

400

The _userId_ does not match ^\[a-zA-Z0-9\_-:@.\]+$

---

404

User of the given _userId_ is not present in the catalog. If there is no additional info in the JSON response, you probably have an error in your URL.

---

## User-Item Interactions

The following methods allow adding, deleting, and listing interactions between the users and the items.

### Detail Views

post

#### Add Detail View

Allowed on Client-Side

Adds a detail view of the given item made by the given user.

```js
client.send(new recombee.AddDetailView(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  duration: 35,                                      // integer
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
}));
```

```kotlin
client.send(AddDetailView(userId, itemId,
    // optional parameters:
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    duration = 35L,                                     // Long
    cascadeCreate = true,                               // Boolean
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
    autoPresented = false,                              // Boolean
))
```

```swift
_ = try await client.send(AddDetailView(userId: userId, itemId: itemId,
    // optional parameters:
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    duration: 35,                                                           // Int
    cascadeCreate: true,                                                    // Bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:],                                                    // JSONDictionary
    autoPresented: false                                                    // Bool
))
```

```js
client.send(new requests.AddDetailView(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  duration: 35,                                      // integer
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
}));
```

```python
client.send(AddDetailView(user_id, item_id,
    # optional parameters:
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    duration=35,                                       # integer
    cascade_create=True,                               # boolean
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
    auto_presented=False,                              # boolean
))
```

```ruby
client.send(AddDetailView.new(user_id, item_id, {
  # optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  duration: 35,                                       # integer
  cascade_create: true,                               # boolean
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
  auto_presented: false,                              # boolean
}))
```

```java
client.send(new AddDetailView(userId, itemId)
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setDuration(35)                                                 // long
    .setCascadeCreate(true)                                          // boolean
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
    .setAutoPresented(false)                                         // boolean
);
```

```php
$client->send(new Reqs\AddDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'duration' => 35,                                      // integer
    'cascadeCreate' => true,                               // boolean
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
    'autoPresented' => false,                              // boolean
]));
```

```csharp
client.Send(new AddDetailView(userId, itemId,
    // optional parameters:
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    duration: 35,                                       // long
    cascadeCreate: true,                                // bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>(),   // Dictionary<string, object>
    autoPresented: false                                // bool
));
```

```go
request := client.NewAddDetailView(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetDuration(35).                                                       // int
    SetCascadeCreate(true).                                                // bool
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{}).                           // map[string]interface{}
    SetAutoPresented(false)                                                // bool

_, err := request.Send()
```

```http
POST /{databaseId}/detailviews/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "timestamp": "2022-05-13T18:25:43Z",
  "duration": 35,
  "cascadeCreate": true,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {},
  "autoPresented": false
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

User who viewed the item

---

itemId

String

Located in: **body**

Required: **Yes**

Viewed item

---

timestamp

String

Number

Located in: **body**

Required: **No**

UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

duration

Integer

Located in: **body**

Required: **No**

Duration of the view

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Sets whether the given user/item should be created if not present in the database.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

autoPresented

Boolean

Located in: **body**

Required: **No**

Since version: **6.0.0**

Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. `timestamp` or `duration` is not a real number ≥ 0.

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A detail view of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. Note that a user may view an item's details multiple times, yet triplets (`userId`, `itemId`, `timestamp`) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Detail View

Deletes an existing detail view uniquely specified by (`userId`, `itemId`, and `timestamp`) or all the detail views with the given `userId` and `itemId` if `timestamp` is omitted.

```js
client.send(new requests.DeleteDetailView(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));
```

```python
client.send(DeleteDetailView(user_id, item_id,
    # optional parameters:
    timestamp=1652466343,  # number
))
```

```ruby
client.send(DeleteDetailView.new(user_id, item_id, {
  # optional parameters:
  timestamp: 1652466343,  # number
}))
```

```java
client.send(new DeleteDetailView(userId, itemId)
    .setTimestamp(Date.from(Instant.ofEpochSecond(1652466343)))  // Date
);
```

```php
$client->send(new Reqs\DeleteDetailView($user_id, $item_id, [
    // optional parameters:
    'timestamp' => 1652466343,  // number
]));
```

```csharp
client.Send(new DeleteDetailView(userId, itemId,
    // optional parameters:
    timestamp: DateTimeOffset.FromUnixTimeSeconds(1652466343).UtcDateTime  // DateTime
));
```

```go
request := client.NewDeleteDetailView(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Unix(1652466343, 0))  // time.Time

_, err := request.Send()
```

```http
DELETE /{databaseId}/detailviews/?userId=user-1
&itemId=item-1
&timestamp=1652466343
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

ID of the user who made the detail view.

---

itemId

String

Located in: **query**

Required: **Yes**

ID of the item whose details were viewed.

---

timestamp

Number

Located in: **query**

Required: **No**

Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with the given `userId` and `itemId` are deleted.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0.

---

404

The `userId`, `itemId`, or detail view with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Detail Views

Lists all the detail views of the given item ever made by different users.

```js
const result = await client.send(new requests.ListItemDetailViews(itemId));
```

```python
result = client.send(ListItemDetailViews(item_id))
```

```ruby
result = client.send(ListItemDetailViews.new(item_id))
```

```java
DetailView[] result = client.send(new ListItemDetailViews(itemId));
```

```php
$result = $client->send(new Reqs\ListItemDetailViews($item_id));
```

```csharp
IEnumerable<DetailView> result = client.Send(new ListItemDetailViews(itemId));
```

```go
request := client.NewListItemDetailViews(itemId)

result, err := request.Send() // result is of the type []bindings.DetailView
```

```http
GET /{databaseId}/items/{itemId}/detailviews/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose detail views are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "autoPresented": true,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "duration": null,
    "autoPresented": false,
    "timestamp": 1348239363.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Detail Views

Lists all the detail views of different items ever made by the given user.

```js
const result = await client.send(new requests.ListUserDetailViews(userId));
```

```python
result = client.send(ListUserDetailViews(user_id))
```

```ruby
result = client.send(ListUserDetailViews.new(user_id))
```

```java
DetailView[] result = client.send(new ListUserDetailViews(userId));
```

```php
$result = $client->send(new Reqs\ListUserDetailViews($user_id));
```

```csharp
IEnumerable<DetailView> result = client.Send(new ListUserDetailViews(userId));
```

```go
request := client.NewListUserDetailViews(userId)

result, err := request.Send() // result is of the type []bindings.DetailView
```

```http
GET /{databaseId}/users/{userId}/detailviews/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user whose detail views are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "duration": 134.03,
    "autoPresented": true,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "duration": 14.23,
    "autoPresented": false,
    "timestamp": 1348151906.0
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Purchases

post

#### Add Purchase

Allowed on Client-Side

Adds a purchase of the given item made by the given user.

```js
client.send(new recombee.AddPurchase(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  profit: 5.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```kotlin
client.send(AddPurchase(userId, itemId,
    // optional parameters:
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    cascadeCreate = true,                               // Boolean
    amount = 1.0,                                       // Double
    price = 25.0,                                       // Double
    profit = 5.0,                                       // Double
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
))
```

```swift
_ = try await client.send(AddPurchase(userId: userId, itemId: itemId,
    // optional parameters:
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    cascadeCreate: true,                                                    // Bool
    amount: 1.0,                                                            // Double
    price: 25.0,                                                            // Double
    profit: 5.0,                                                            // Double
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:]                                                     // JSONDictionary
))
```

```js
client.send(new requests.AddPurchase(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  profit: 5.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```python
client.send(AddPurchase(user_id, item_id,
    # optional parameters:
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    cascade_create=True,                               # boolean
    amount=1,                                          # number
    price=25.0,                                        # number
    profit=5.0,                                        # number
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
))
```

```ruby
client.send(AddPurchase.new(user_id, item_id, {
  # optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  cascade_create: true,                               # boolean
  amount: 1,                                          # number
  price: 25.0,                                        # number
  profit: 5.0,                                        # number
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
}))
```

```java
client.send(new AddPurchase(userId, itemId)
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setCascadeCreate(true)                                          // boolean
    .setAmount(1.0)                                                  // double
    .setPrice(25.0)                                                  // double
    .setProfit(5.0)                                                  // double
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
);
```

```php
$client->send(new Reqs\AddPurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'cascadeCreate' => true,                               // boolean
    'amount' => 1,                                         // number
    'price' => 25.0,                                       // number
    'profit' => 5.0,                                       // number
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
]));
```

```csharp
client.Send(new AddPurchase(userId, itemId,
    // optional parameters:
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    cascadeCreate: true,                                // bool
    amount: 1.0,                                        // double
    price: 25.0,                                        // double
    profit: 5.0,                                        // double
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>()    // Dictionary<string, object>
));
```

```go
request := client.NewAddPurchase(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetCascadeCreate(true).                                                // bool
    SetAmount(1.0).                                                        // float64
    SetPrice(25.0).                                                        // float64
    SetProfit(5.0).                                                        // float64
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{})                            // map[string]interface{}

_, err := request.Send()
```

```http
POST /{databaseId}/purchases/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "timestamp": "2022-05-13T18:25:43Z",
  "cascadeCreate": true,
  "amount": 1,
  "price": 25.0,
  "profit": 5.0,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {}
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

User who purchased the item

---

itemId

String

Located in: **body**

Required: **Yes**

Purchased item

---

timestamp

String

Number

Located in: **body**

Required: **No**

UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Sets whether the given user/item should be created if not present in the database.

---

amount

Number

Located in: **body**

Required: **No**

Since version: **1.6.0**

Amount (number) of purchased items. The default is 1\. For example, if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal 2.

---

price

Number

Located in: **body**

Required: **No**

Since version: **1.6.0**

Price paid by the user for the item. If `amount` is greater than 1, the sum of prices of all the items should be given.

---

profit

Number

Located in: **body**

Required: **No**

Since version: **1.6.0**

Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If `amount` is greater than 1, the sum of profit of all the items should be given.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

##### Responses

200

Successful operation.

---

400

The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$. `timestamp` is not a real number ≥ 0.

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A purchase of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Purchase

Deletes an existing purchase uniquely specified by `userId`, `itemId`, and `timestamp` or all the purchases with the given `userId` and `itemId` if `timestamp` is omitted.

```js
client.send(new requests.DeletePurchase(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));
```

```python
client.send(DeletePurchase(user_id, item_id,
    # optional parameters:
    timestamp=1652466343,  # number
))
```

```ruby
client.send(DeletePurchase.new(user_id, item_id, {
  # optional parameters:
  timestamp: 1652466343,  # number
}))
```

```java
client.send(new DeletePurchase(userId, itemId)
    .setTimestamp(Date.from(Instant.ofEpochSecond(1652466343)))  // Date
);
```

```php
$client->send(new Reqs\DeletePurchase($user_id, $item_id, [
    // optional parameters:
    'timestamp' => 1652466343,  // number
]));
```

```csharp
client.Send(new DeletePurchase(userId, itemId,
    // optional parameters:
    timestamp: DateTimeOffset.FromUnixTimeSeconds(1652466343).UtcDateTime  // DateTime
));
```

```go
request := client.NewDeletePurchase(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Unix(1652466343, 0))  // time.Time

_, err := request.Send()
```

```http
DELETE /{databaseId}/purchases/?userId=user-1
&itemId=item-1
&timestamp=1652466343
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

ID of the user who made the purchase.

---

itemId

String

Located in: **query**

Required: **Yes**

ID of the item which was purchased.

---

timestamp

Number

Located in: **query**

Required: **No**

Unix timestamp of the purchase. If the `timestamp` is omitted, then all the purchases with the given `userId` and `itemId` are deleted.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0.

---

404

The `userId`, `itemId`, or purchase with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Purchases

Lists all the ever-made purchases of the given item.

```js
const result = await client.send(new requests.ListItemPurchases(itemId));
```

```python
result = client.send(ListItemPurchases(item_id))
```

```ruby
result = client.send(ListItemPurchases.new(item_id))
```

```java
Purchase[] result = client.send(new ListItemPurchases(itemId));
```

```php
$result = $client->send(new Reqs\ListItemPurchases($item_id));
```

```csharp
IEnumerable<Purchase> result = client.Send(new ListItemPurchases(itemId));
```

```go
request := client.NewListItemPurchases(itemId)

result, err := request.Send() // result is of the type []bindings.Purchase
```

```http
GET /{databaseId}/items/{itemId}/purchases/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose purchases are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "timestamp": 1348327154.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Purchases

Lists all the purchases ever made by the given user.

```js
const result = await client.send(new requests.ListUserPurchases(userId));
```

```python
result = client.send(ListUserPurchases(user_id))
```

```ruby
result = client.send(ListUserPurchases.new(user_id))
```

```java
Purchase[] result = client.send(new ListUserPurchases(userId));
```

```php
$result = $client->send(new Reqs\ListUserPurchases($user_id));
```

```csharp
IEnumerable<Purchase> result = client.Send(new ListUserPurchases(userId));
```

```go
request := client.NewListUserPurchases(userId)

result, err := request.Send() // result is of the type []bindings.Purchase
```

```http
GET /{databaseId}/users/{userId}/purchases/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user whose purchases are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Ratings

post

#### Add Rating

Allowed on Client-Side

Adds a rating of the given item made by the given user.

```js
client.send(new recombee.AddRating(userId, itemId, rating, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```kotlin
client.send(AddRating(userId, itemId, rating,
    // optional parameters:
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    cascadeCreate = true,                               // Boolean
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
))
```

```swift
_ = try await client.send(AddRating(userId: userId, itemId: itemId, rating: rating,
    // optional parameters:
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    cascadeCreate: true,                                                    // Bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:]                                                     // JSONDictionary
))
```

```js
client.send(new requests.AddRating(userId, itemId, rating, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```python
client.send(AddRating(user_id, item_id, rating,
    # optional parameters:
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    cascade_create=True,                               # boolean
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
))
```

```ruby
client.send(AddRating.new(user_id, item_id, rating, {
  # optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  cascade_create: true,                               # boolean
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
}))
```

```java
client.send(new AddRating(userId, itemId, rating)
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setCascadeCreate(true)                                          // boolean
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
);
```

```php
$client->send(new Reqs\AddRating($user_id, $item_id, $rating, [
    // optional parameters:
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'cascadeCreate' => true,                               // boolean
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
]));
```

```csharp
client.Send(new AddRating(userId, itemId, rating,
    // optional parameters:
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    cascadeCreate: true,                                // bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>()    // Dictionary<string, object>
));
```

```go
request := client.NewAddRating(userId, itemId, rating).
    // optional parameters:
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetCascadeCreate(true).                                                // bool
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{})                            // map[string]interface{}

_, err := request.Send()
```

```http
POST /{databaseId}/ratings/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "timestamp": "2022-05-13T18:25:43Z",
  "rating": 0.5,
  "cascadeCreate": true,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {}
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

User who submitted the rating

---

itemId

String

Located in: **body**

Required: **Yes**

Rated item

---

timestamp

String

Number

Located in: **body**

Required: **No**

UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

rating

Number

Located in: **body**

Required: **Yes**

Rating rescaled to interval \[-1.0,1.0\], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Sets whether the given user/item should be created if not present in the database.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

##### Responses

200

Successful operation.

---

400

The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or rating is not a real number from \[-1.0,1.0\], or timestamp is not a real number ≥ 0.

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A rating of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. Note that a user may rate an item multiple times, yet triplets (userId, itemId, timestamp) must be unique. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Rating

Deletes an existing rating specified by (`userId`, `itemId`, `timestamp`) from the database or all the ratings with the given `userId` and `itemId` if `timestamp` is omitted.

```js
client.send(new requests.DeleteRating(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));
```

```python
client.send(DeleteRating(user_id, item_id,
    # optional parameters:
    timestamp=1652466343,  # number
))
```

```ruby
client.send(DeleteRating.new(user_id, item_id, {
  # optional parameters:
  timestamp: 1652466343,  # number
}))
```

```java
client.send(new DeleteRating(userId, itemId)
    .setTimestamp(Date.from(Instant.ofEpochSecond(1652466343)))  // Date
);
```

```php
$client->send(new Reqs\DeleteRating($user_id, $item_id, [
    // optional parameters:
    'timestamp' => 1652466343,  // number
]));
```

```csharp
client.Send(new DeleteRating(userId, itemId,
    // optional parameters:
    timestamp: DateTimeOffset.FromUnixTimeSeconds(1652466343).UtcDateTime  // DateTime
));
```

```go
request := client.NewDeleteRating(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Unix(1652466343, 0))  // time.Time

_, err := request.Send()
```

```http
DELETE /{databaseId}/ratings/?userId=user-1
&itemId=item-1
&timestamp=1652466343
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

ID of the user who rated the item.

---

itemId

String

Located in: **query**

Required: **Yes**

ID of the item which was rated.

---

timestamp

Number

Located in: **query**

Required: **No**

Unix timestamp of the rating. If the `timestamp` is omitted, then all the ratings with the given `userId` and `itemId` are deleted.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0.

---

404

The `userId`, `itemId` or rating with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Ratings

Lists all the ratings of an item ever submitted by different users.

```js
const result = await client.send(new requests.ListItemRatings(itemId));
```

```python
result = client.send(ListItemRatings(item_id))
```

```ruby
result = client.send(ListItemRatings.new(item_id))
```

```java
Rating[] result = client.send(new ListItemRatings(itemId));
```

```php
$result = $client->send(new Reqs\ListItemRatings($item_id));
```

```csharp
IEnumerable<Rating> result = client.Send(new ListItemRatings(itemId));
```

```go
request := client.NewListItemRatings(itemId)

result, err := request.Send() // result is of the type []bindings.Rating
```

```http
GET /{databaseId}/items/{itemId}/ratings/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose ratings are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "rating": 0.0,
    "timestamp": 1348239363.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Ratings

Lists all the ratings ever submitted by the given user.

```js
const result = await client.send(new requests.ListUserRatings(userId));
```

```python
result = client.send(ListUserRatings(user_id))
```

```ruby
result = client.send(ListUserRatings.new(user_id))
```

```java
Rating[] result = client.send(new ListUserRatings(userId));
```

```php
$result = $client->send(new Reqs\ListUserRatings($user_id));
```

```csharp
IEnumerable<Rating> result = client.Send(new ListUserRatings(userId));
```

```go
request := client.NewListUserRatings(userId)

result, err := request.Send() // result is of the type []bindings.Rating
```

```http
GET /{databaseId}/users/{userId}/ratings/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user whose ratings are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-y",
    "userId": "user-a",
    "rating": 0.5,
    "timestamp": 1348139180.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "rating": -0.25,
    "timestamp": 1348151906.0
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Cart Additions

post

#### Add Cart Addition

Allowed on Client-Side

Adds a cart addition of the given item made by the given user.

```js
client.send(new recombee.AddCartAddition(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```kotlin
client.send(AddCartAddition(userId, itemId,
    // optional parameters:
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    cascadeCreate = true,                               // Boolean
    amount = 1.0,                                       // Double
    price = 25.0,                                       // Double
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
))
```

```swift
_ = try await client.send(AddCartAddition(userId: userId, itemId: itemId,
    // optional parameters:
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    cascadeCreate: true,                                                    // Bool
    amount: 1.0,                                                            // Double
    price: 25.0,                                                            // Double
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:]                                                     // JSONDictionary
))
```

```js
client.send(new requests.AddCartAddition(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  amount: 1,                                         // number
  price: 25.0,                                       // number
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```python
client.send(AddCartAddition(user_id, item_id,
    # optional parameters:
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    cascade_create=True,                               # boolean
    amount=1,                                          # number
    price=25.0,                                        # number
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
))
```

```ruby
client.send(AddCartAddition.new(user_id, item_id, {
  # optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  cascade_create: true,                               # boolean
  amount: 1,                                          # number
  price: 25.0,                                        # number
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
}))
```

```java
client.send(new AddCartAddition(userId, itemId)
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setCascadeCreate(true)                                          // boolean
    .setAmount(1.0)                                                  // double
    .setPrice(25.0)                                                  // double
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
);
```

```php
$client->send(new Reqs\AddCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'cascadeCreate' => true,                               // boolean
    'amount' => 1,                                         // number
    'price' => 25.0,                                       // number
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
]));
```

```csharp
client.Send(new AddCartAddition(userId, itemId,
    // optional parameters:
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    cascadeCreate: true,                                // bool
    amount: 1.0,                                        // double
    price: 25.0,                                        // double
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>()    // Dictionary<string, object>
));
```

```go
request := client.NewAddCartAddition(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetCascadeCreate(true).                                                // bool
    SetAmount(1.0).                                                        // float64
    SetPrice(25.0).                                                        // float64
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{})                            // map[string]interface{}

_, err := request.Send()
```

```http
POST /{databaseId}/cartadditions/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "timestamp": "2022-05-13T18:25:43Z",
  "cascadeCreate": true,
  "amount": 1,
  "price": 25.0,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {}
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

User who added the item to the cart

---

itemId

String

Located in: **body**

Required: **Yes**

Item added to the cart

---

timestamp

String

Number

Located in: **body**

Required: **No**

UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Sets whether the given user/item should be created if not present in the database.

---

amount

Number

Located in: **body**

Required: **No**

Since version: **1.6.0**

Amount (number) added to cart. The default is 1\. For example, if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal 2.

---

price

Number

Located in: **body**

Required: **No**

Since version: **1.6.0**

Price of the added item. If `amount` is greater than 1, the sum of prices of all the items should be given.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

##### Responses

200

Successful operation.

---

400

The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, `timestamp` is not a real number ≥ 0.

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A cart addition of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Cart Addition

Deletes an existing cart addition uniquely specified by `userId`, `itemId`, and `timestamp` or all the cart additions with the given `userId` and `itemId` if `timestamp` is omitted.

```js
client.send(new requests.DeleteCartAddition(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));
```

```python
client.send(DeleteCartAddition(user_id, item_id,
    # optional parameters:
    timestamp=1652466343,  # number
))
```

```ruby
client.send(DeleteCartAddition.new(user_id, item_id, {
  # optional parameters:
  timestamp: 1652466343,  # number
}))
```

```java
client.send(new DeleteCartAddition(userId, itemId)
    .setTimestamp(Date.from(Instant.ofEpochSecond(1652466343)))  // Date
);
```

```php
$client->send(new Reqs\DeleteCartAddition($user_id, $item_id, [
    // optional parameters:
    'timestamp' => 1652466343,  // number
]));
```

```csharp
client.Send(new DeleteCartAddition(userId, itemId,
    // optional parameters:
    timestamp: DateTimeOffset.FromUnixTimeSeconds(1652466343).UtcDateTime  // DateTime
));
```

```go
request := client.NewDeleteCartAddition(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Unix(1652466343, 0))  // time.Time

_, err := request.Send()
```

```http
DELETE /{databaseId}/cartadditions/?userId=user-1
&itemId=item-1
&timestamp=1652466343
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

ID of the user who made the cart addition.

---

itemId

String

Located in: **query**

Required: **Yes**

ID of the item which was added to the cart.

---

timestamp

Number

Located in: **query**

Required: **No**

Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with the given `userId` and `itemId` are deleted.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0.

---

404

The `userId`, `itemId`, or cart addition with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Cart Additions

Lists all the ever-made cart additions of the given item.

```js
const result = await client.send(new requests.ListItemCartAdditions(itemId));
```

```python
result = client.send(ListItemCartAdditions(item_id))
```

```ruby
result = client.send(ListItemCartAdditions.new(item_id))
```

```java
CartAddition[] result = client.send(new ListItemCartAdditions(itemId));
```

```php
$result = $client->send(new Reqs\ListItemCartAdditions($item_id));
```

```csharp
IEnumerable<CartAddition> result = client.Send(new ListItemCartAdditions(itemId));
```

```go
request := client.NewListItemCartAdditions(itemId)

result, err := request.Send() // result is of the type []bindings.CartAddition
```

```http
GET /{databaseId}/items/{itemId}/cartadditions/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose cart additions are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Cart Additions

Lists all the cart additions ever made by the given user.

```js
const result = await client.send(new requests.ListUserCartAdditions(userId));
```

```python
result = client.send(ListUserCartAdditions(user_id))
```

```ruby
result = client.send(ListUserCartAdditions.new(user_id))
```

```java
CartAddition[] result = client.send(new ListUserCartAdditions(userId));
```

```php
$result = $client->send(new Reqs\ListUserCartAdditions($user_id));
```

```csharp
IEnumerable<CartAddition> result = client.Send(new ListUserCartAdditions(userId));
```

```go
request := client.NewListUserCartAdditions(userId)

result, err := request.Send() // result is of the type []bindings.CartAddition
```

```http
GET /{databaseId}/users/{userId}/cartadditions/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user whose cart additions are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Bookmarks

post

#### Add Bookmark

Allowed on Client-Side

Adds a bookmark of the given item made by the given user.

```js
client.send(new recombee.AddBookmark(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```kotlin
client.send(AddBookmark(userId, itemId,
    // optional parameters:
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    cascadeCreate = true,                               // Boolean
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
))
```

```swift
_ = try await client.send(AddBookmark(userId: userId, itemId: itemId,
    // optional parameters:
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    cascadeCreate: true,                                                    // Bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:]                                                     // JSONDictionary
))
```

```js
client.send(new requests.AddBookmark(userId, itemId, {
  // optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
}));
```

```python
client.send(AddBookmark(user_id, item_id,
    # optional parameters:
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    cascade_create=True,                               # boolean
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
))
```

```ruby
client.send(AddBookmark.new(user_id, item_id, {
  # optional parameters:
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  cascade_create: true,                               # boolean
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
}))
```

```java
client.send(new AddBookmark(userId, itemId)
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setCascadeCreate(true)                                          // boolean
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
);
```

```php
$client->send(new Reqs\AddBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'cascadeCreate' => true,                               // boolean
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
]));
```

```csharp
client.Send(new AddBookmark(userId, itemId,
    // optional parameters:
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    cascadeCreate: true,                                // bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>()    // Dictionary<string, object>
));
```

```go
request := client.NewAddBookmark(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetCascadeCreate(true).                                                // bool
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{})                            // map[string]interface{}

_, err := request.Send()
```

```http
POST /{databaseId}/bookmarks/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "timestamp": "2022-05-13T18:25:43Z",
  "cascadeCreate": true,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {}
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

User who bookmarked the item

---

itemId

String

Located in: **body**

Required: **Yes**

Bookmarked item

---

timestamp

String

Number

Located in: **body**

Required: **No**

UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Sets whether the given user/item should be created if not present in the database.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

##### Responses

200

Successful operation.

---

400

The `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, `timestamp` is not a real number ≥ 0.

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A bookmark of the exact same `userId`, `itemId`, and `timestamp` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Bookmark

Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp` or all the bookmarks with the given `userId` and `itemId` if `timestamp` is omitted.

```js
client.send(new requests.DeleteBookmark(userId, itemId, {
  // optional parameters:
  timestamp: 1652466343,  // number
}));
```

```python
client.send(DeleteBookmark(user_id, item_id,
    # optional parameters:
    timestamp=1652466343,  # number
))
```

```ruby
client.send(DeleteBookmark.new(user_id, item_id, {
  # optional parameters:
  timestamp: 1652466343,  # number
}))
```

```java
client.send(new DeleteBookmark(userId, itemId)
    .setTimestamp(Date.from(Instant.ofEpochSecond(1652466343)))  // Date
);
```

```php
$client->send(new Reqs\DeleteBookmark($user_id, $item_id, [
    // optional parameters:
    'timestamp' => 1652466343,  // number
]));
```

```csharp
client.Send(new DeleteBookmark(userId, itemId,
    // optional parameters:
    timestamp: DateTimeOffset.FromUnixTimeSeconds(1652466343).UtcDateTime  // DateTime
));
```

```go
request := client.NewDeleteBookmark(userId, itemId).
    // optional parameters:
    SetTimestamp(time.Unix(1652466343, 0))  // time.Time

_, err := request.Send()
```

```http
DELETE /{databaseId}/bookmarks/?userId=user-1
&itemId=item-1
&timestamp=1652466343
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

ID of the user who made the bookmark.

---

itemId

String

Located in: **query**

Required: **Yes**

ID of the item which was bookmarked.

---

timestamp

Number

Located in: **query**

Required: **No**

Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with the given `userId` and `itemId` are deleted.

---

##### Responses

200

Successful operation.

---

400

Given `userId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `timestamp` is not a real number ≥ 0.

---

404

The `userId`, `itemId`, or bookmark with the given (`userId`, `itemId`, `timestamp`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item Bookmarks

Lists all the ever-made bookmarks of the given item.

```js
const result = await client.send(new requests.ListItemBookmarks(itemId));
```

```python
result = client.send(ListItemBookmarks(item_id))
```

```ruby
result = client.send(ListItemBookmarks.new(item_id))
```

```java
Bookmark[] result = client.send(new ListItemBookmarks(itemId));
```

```php
$result = $client->send(new Reqs\ListItemBookmarks($item_id));
```

```csharp
IEnumerable<Bookmark> result = client.Send(new ListItemBookmarks(itemId));
```

```go
request := client.NewListItemBookmarks(itemId)

result, err := request.Send() // result is of the type []bindings.Bookmark
```

```http
GET /{databaseId}/items/{itemId}/bookmarks/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

ID of the item whose bookmarks are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-a",
    "timestamp": 1348327154.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User Bookmarks

Lists all the bookmarks ever made by the given user.

```js
const result = await client.send(new requests.ListUserBookmarks(userId));
```

```python
result = client.send(ListUserBookmarks(user_id))
```

```ruby
result = client.send(ListUserBookmarks.new(user_id))
```

```java
Bookmark[] result = client.send(new ListUserBookmarks(userId));
```

```php
$result = $client->send(new Reqs\ListUserBookmarks($user_id));
```

```csharp
IEnumerable<Bookmark> result = client.Send(new ListUserBookmarks(userId));
```

```go
request := client.NewListUserBookmarks(userId)

result, err := request.Send() // result is of the type []bindings.Bookmark
```

```http
GET /{databaseId}/users/{userId}/bookmarks/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

ID of the user whose bookmarks are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "timestamp": 1348151906.0,
    "userId": "user-a"
  },
  {
    "itemId": "item-z",
    "timestamp": 1348239363.0,
    "userId": "user-a"
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### View Portions

post

#### Set View Portion

Allowed on Client-Side

Sets viewed portion of an item (for example a video or article) by a user (at a session). If you send a new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.

```js
client.send(new recombee.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  sessionId: 'ABAD1D',                               // string
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
  timeSpent: 42,                                     // number
}));
```

```kotlin
client.send(SetViewPortion(userId, itemId, portion,
    // optional parameters:
    sessionId = "ABAD1D",                               // String
    timestamp = Instant.parse("2022-05-13T18:25:43Z"),  // Instant
    cascadeCreate = true,                               // Boolean
    recommId = "ce52ada4-e4d9-4885-943c-407db2dee837",  // String
    additionalData = emptyMap(),                        // Map<String, Any>
    autoPresented = false,                              // Boolean
    timeSpent = 42.0,                                   // Double
))
```

```swift
_ = try await client.send(SetViewPortion(userId: userId, itemId: itemId, portion: portion,
    // optional parameters:
    sessionId: "ABAD1D",                                                    // String
    timestamp: ISO8601DateFormatter().date(from: "2022-05-13T18:25:43Z")!,  // Date
    cascadeCreate: true,                                                    // Bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",                       // String
    additionalData: [:],                                                    // JSONDictionary
    autoPresented: false,                                                   // Bool
    timeSpent: 42.0                                                         // Double
))
```

```js
client.send(new requests.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  sessionId: 'ABAD1D',                               // string
  timestamp: '2022-05-13T18:25:43Z',                 // string / number
  cascadeCreate: true,                               // boolean
  recommId: 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
  additionalData: {},                                // Object
  autoPresented: false,                              // boolean
  timeSpent: 42,                                     // number
}));
```

```python
client.send(SetViewPortion(user_id, item_id, portion,
    # optional parameters:
    session_id='ABAD1D',                               # string
    timestamp='2022-05-13T18:25:43Z',                  # string / number
    cascade_create=True,                               # boolean
    recomm_id='ce52ada4-e4d9-4885-943c-407db2dee837',  # string
    additional_data={},                                # dict
    auto_presented=False,                              # boolean
    time_spent=42,                                     # number
))
```

```ruby
client.send(SetViewPortion.new(user_id, item_id, portion, {
  # optional parameters:
  session_id: 'ABAD1D',                               # string
  timestamp: '2022-05-13T18:25:43Z',                  # string / number
  cascade_create: true,                               # boolean
  recomm_id: 'ce52ada4-e4d9-4885-943c-407db2dee837',  # string
  additional_data: {},                                # Hash
  auto_presented: false,                              # boolean
  time_spent: 42,                                     # number
}))
```

```java
client.send(new SetViewPortion(userId, itemId, portion)
    .setSessionId("ABAD1D")                                          // String
    .setTimestamp(Date.from(Instant.parse("2022-05-13T18:25:43Z")))  // Date
    .setCascadeCreate(true)                                          // boolean
    .setRecommId("ce52ada4-e4d9-4885-943c-407db2dee837")             // String
    .setAdditionalData(new HashMap<String, Object>())                // Map<String, Object>
    .setAutoPresented(false)                                         // boolean
    .setTimeSpent(42.0)                                              // double
);
```

```php
$client->send(new Reqs\SetViewPortion($user_id, $item_id, $portion, [
    // optional parameters:
    'sessionId' => 'ABAD1D',                               // string
    'timestamp' => '2022-05-13T18:25:43Z',                 // string / number
    'cascadeCreate' => true,                               // boolean
    'recommId' => 'ce52ada4-e4d9-4885-943c-407db2dee837',  // string
    'additionalData' => [],                                // array (map)
    'autoPresented' => false,                              // boolean
    'timeSpent' => 42,                                     // number
]));
```

```csharp
client.Send(new SetViewPortion(userId, itemId, portion,
    // optional parameters:
    sessionId: "ABAD1D",                                // string
    timestamp: DateTime.Parse("2022-05-13T18:25:43Z"),  // DateTime
    cascadeCreate: true,                                // bool
    recommId: "ce52ada4-e4d9-4885-943c-407db2dee837",   // string
    additionalData: new Dictionary<string, object>(),   // Dictionary<string, object>
    autoPresented: false,                               // bool
    timeSpent: 42.0                                     // double
));
```

```go
request := client.NewSetViewPortion(userId, itemId, portion).
    // optional parameters:
    SetSessionId("ABAD1D").                                                // string
    SetTimestamp(time.Date(2022, time.May, 13, 18, 25, 43, 0, time.UTC)).  // time.Time
    SetCascadeCreate(true).                                                // bool
    SetRecommId("ce52ada4-e4d9-4885-943c-407db2dee837").                   // string
    SetAdditionalData(map[string]interface{}{}).                           // map[string]interface{}
    SetAutoPresented(false).                                               // bool
    SetTimeSpent(42.0)                                                     // float64

_, err := request.Send()
```

```http
POST /{databaseId}/viewportions/
Body (application/json):
{
  "userId": "user-1",
  "itemId": "item-1",
  "portion": 0.5,
  "sessionId": "ABAD1D",
  "timestamp": "2022-05-13T18:25:43Z",
  "cascadeCreate": true,
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "additionalData": {},
  "autoPresented": false,
  "timeSpent": 42
}
```

---

Since version

2.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of your database.

---

userId

String

Located in: **body**

Required: **Yes**

Since version: **2.1.0**

User who viewed a portion of the item

---

itemId

String

Located in: **body**

Required: **Yes**

Since version: **2.1.0**

Viewed item

---

portion

Number

Located in: **body**

Required: **Yes**

Since version: **2.1.0**

Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`.

---

sessionId

String

Located in: **body**

Required: **No**

Since version: **2.1.0**

ID of the session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc., depending on the language).

---

timestamp

String

Number

Located in: **body**

Required: **No**

Since version: **2.1.0**

UTC timestamp of the view portion as ISO8601-1 pattern or UTC epoch time. The default value is the current time.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Since version: **2.1.0**

Sets whether the given user/item should be created if not present in the database.

---

recommId

String

Located in: **body**

Required: **No**

Since version: **2.2.0**

If this view portion is based on a recommendation request, `recommId` is the id of the clicked recommendation.

---

additionalData

Object

Located in: **body**

Required: **No**

Since version: **2.3.0**

Additional data associated with the interaction. The expected structure is defined for specific use cases and will be provided by the Recombee Support team when applicable.

---

autoPresented

Boolean

Located in: **body**

Required: **No**

Since version: **6.0.0**

Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`.

---

timeSpent

Number

Located in: **body**

Required: **No**

Since version: **6.0.0**

The duration (in seconds) that the user viewed the item. In update requests, this value may only increase and is required only if it has changed.

---

##### Responses

200

Successful operation.

---

400

The `userId`, `itemId` or `sessionId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or the `portion` is not a real number from \[0.0,1.0\].

---

404

The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A view portion of the exact same `userId`, `itemId`, and a greater or equal `timestamp` (or a greater `portion`) is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete View Portion

Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database.

```js
client.send(new requests.DeleteViewPortion(userId, itemId, {
  // optional parameters:
  sessionId: 'ABAD1D',  // string
}));
```

```python
client.send(DeleteViewPortion(user_id, item_id,
    # optional parameters:
    session_id='ABAD1D',  # string
))
```

```ruby
client.send(DeleteViewPortion.new(user_id, item_id, {
  # optional parameters:
  session_id: 'ABAD1D',  # string
}))
```

```java
client.send(new DeleteViewPortion(userId, itemId)
    .setSessionId("ABAD1D")  // String
);
```

```php
$client->send(new Reqs\DeleteViewPortion($user_id, $item_id, [
    // optional parameters:
    'sessionId' => 'ABAD1D',  // string
]));
```

```csharp
client.Send(new DeleteViewPortion(userId, itemId,
    // optional parameters:
    sessionId: "ABAD1D"  // string
));
```

```go
request := client.NewDeleteViewPortion(userId, itemId).
    // optional parameters:
    SetSessionId("ABAD1D")  // string

_, err := request.Send()
```

```http
DELETE /{databaseId}/viewportions/?userId=user-1
&itemId=item-1
&sessionId=ABAD1D
```

---

Since version

2.1.0

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of your database.

---

userId

String

Located in: **query**

Required: **Yes**

Since version: **2.1.0**

ID of the user who rated the item.

---

itemId

String

Located in: **query**

Required: **Yes**

Since version: **2.1.0**

ID of the item which was rated.

---

sessionId

String

Located in: **query**

Required: **No**

Since version: **2.1.0**

Identifier of a session.

---

##### Responses

200

Successful operation.

---

400

Given `userId`, `itemId` or `sessionId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

The `userId`, `itemId` or view portion with the given (`userId`, `itemId`, `sessionId`) not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Item View Portions

Lists all the view portions of an item ever submitted by different users.

```js
const result = await client.send(new requests.ListItemViewPortions(itemId));
```

```python
result = client.send(ListItemViewPortions(item_id))
```

```ruby
result = client.send(ListItemViewPortions.new(item_id))
```

```java
ViewPortion[] result = client.send(new ListItemViewPortions(itemId));
```

```php
$result = $client->send(new Reqs\ListItemViewPortions($item_id));
```

```csharp
IEnumerable<ViewPortion> result = client.Send(new ListItemViewPortions(itemId));
```

```go
request := client.NewListItemViewPortions(itemId)

result, err := request.Send() // result is of the type []bindings.ViewPortion
```

```http
GET /{databaseId}/items/{itemId}/viewportions/
```

---

Since version

2.1.0

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of the item whose view portions are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.5,
    "autoPresented": true,
    "timeSpent": 40.5,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-x",
    "userId": "user-b",
    "sessionId": null,
    "portion": 1,
    "autoPresented": false,
    "timeSpent": 0,
    "timestamp": 1348239363.0
  }
]
```

---

400

The `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `itemId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List User View Portions

Lists all the view portions ever submitted by the given user.

```js
const result = await client.send(new requests.ListUserViewPortions(userId));
```

```python
result = client.send(ListUserViewPortions(user_id))
```

```ruby
result = client.send(ListUserViewPortions.new(user_id))
```

```java
ViewPortion[] result = client.send(new ListUserViewPortions(userId));
```

```php
$result = $client->send(new Reqs\ListUserViewPortions($user_id));
```

```csharp
IEnumerable<ViewPortion> result = client.Send(new ListUserViewPortions(userId));
```

```go
request := client.NewListUserViewPortions(userId)

result, err := request.Send() // result is of the type []bindings.ViewPortion
```

```http
GET /{databaseId}/users/{userId}/viewportions/
```

---

Since version

2.1.0

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **2.1.0**

ID of the user whose view portions are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemId": "item-x",
    "userId": "user-a",
    "sessionId": "ABAD1D",
    "portion": 0.25,
    "autoPresented": false,
    "timeSpent": 1.5,
    "timestamp": 1348151906.0
  },
  {
    "itemId": "item-y",
    "userId": "user-a",
    "sessionId": "EWQKOL",
    "portion": 0.1,
    "autoPresented": true,
    "timeSpent": 231.25,
    "timestamp": 1348239363.0
  }
]
```

---

400

The `userId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Given `userId` not found in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

## Recommendations

Recommendation methods are capable of recommending items (Recommend Items to User, Recommend Items to Item) or users (Recommend Users to Item, Recommend Users to User).

See Segmentations section for recommendation endpoints that return Segments (e.g. "recommend categories to a user").

### Recommending Items

Recommendation endpoints that return the Items (content, products, etc.).

get

#### Recommend Items to User

Allowed on Client-Side

Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user.

The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:

* Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics).
* Get subsequent recommended items when the user scrolls down (_infinite scroll_) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items).

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemsToUser(userId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:default',                                             // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```kotlin
val result = client.sendAsync(RecommendItemsToUser(userId, count,
    // optional parameters:
    scenario = "homepage",                                                // String
    cascadeCreate = true,                                                 // Boolean
    returnProperties = true,                                              // Boolean
    includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
    filter = "price > 50",                                                // String
    booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic = Logic(name = "recombee:default"),                             // Logic
    reqlExpressions = mapOf(
        "isInUsersCity" to "context_user[\"city\"] in 'cities'",
    ),                                                                    // Map<String, String>
    minRelevance = "low",                                                 // String
    rotationRate = 0.1,                                                   // Double
    rotationTime = 7200.0,                                                // Double
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemsToUser(userId: userId, count: count,
    // optional parameters:
    scenario: "homepage",                                                // String
    cascadeCreate: true,                                                 // Bool
    returnProperties: true,                                              // Bool
    includedProperties: ["title", "price", "publishedAt"],               // [String]
    filter: "price > 50",                                                // String
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic: Logic(name: "recombee:default"),                              // Logic
    reqlExpressions: [
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    ],                                                                   // JSONDictionary
    minRelevance: "low",                                                 // String
    rotationRate: 0.1,                                                   // Double
    rotationTime: 7200.0                                                 // Double
))
```

```js
const result = await client.send(new requests.RecommendItemsToUser(userId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:default',                                             // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```python
result = client.send(RecommendItemsToUser(user_id, count,
    # optional parameters:
    scenario='homepage',                                                # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['title', 'price', 'publishedAt'],              # array
    filter='price > 50',                                                # string
    booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic='recombee:default',                                           # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
    min_relevance='low',                                                # string
    rotation_rate=0.1,                                                  # number
    rotation_time=7200.0,                                               # number
))
```

```ruby
result = client.send(RecommendItemsToUser.new(user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['title', 'price', 'publishedAt'],              # array
  filter: 'price > 50',                                                # string
  booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
  logic: 'recombee:default',                                           # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
  min_relevance: 'low',                                                # string
  rotation_rate: 0.1,                                                  # number
  rotation_time: 7200.0,                                               # number
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemsToUser(userId, count)
    .setScenario("homepage")                                                // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
    .setFilter("price > 50")                                                // String
    .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
    .setLogic(new Logic("recombee:default"))                                // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
    .setMinRelevance("low")                                                 // String
    .setRotationRate(0.1)                                                   // double
    .setRotationTime(7200.0)                                                // double
);
```

```php
$result = $client->send(new Reqs\RecommendItemsToUser($user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['title', 'price', 'publishedAt'],               // array
    'filter' => 'price > 50',                                                // string
    'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
    'minRelevance' => 'low',                                                 // string
    'rotationRate' => 0.1,                                                   // number
    'rotationTime' => 7200.0,                                                // number
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemsToUser(userId, count,
    // optional parameters:
    scenario: "homepage",                                                  // string
    cascadeCreate: true,                                                   // bool
    returnProperties: true,                                                // bool
    includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
    filter: "price > 50",                                                  // string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
    logic: new Logic(name: "recombee:default"),                            // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    },                                                                     // Dictionary<string, string>
    minRelevance: "low",                                                   // string
    rotationRate: 0.1,                                                     // double
    rotationTime: 7200.0                                                   // double
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendItemsToUser(userId, count).
    // optional parameters:
    SetScenario("homepage").                                                // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"title", "price", "publishedAt"}).       // []string
    SetFilter("price > 50").                                                // string
    SetBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    }).                                                                     // map[string]string
    SetMinRelevance("low").                                                 // string
    SetRotationRate(0.1).                                                   // float64
    SetRotationTime(7200.0)                                                 // float64

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/users/{userId}/items/?count=10
&scenario=homepage
&cascadeCreate=true
&returnProperties=true
&includedProperties=title,price,publishedAt
&filter=price > 50
&booster=if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1
&logic=recombee:default
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
&minRelevance=low
&rotationRate=0.1
&rotationTime=7200.0
```

---

Since version

2.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of the user for whom personalized recommendations are to be generated.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **2.0.0**

Number of items to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.

Example response:

```
  {
    "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
    "recomms": 
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
     "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **2.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  {
    "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **2.4.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

minRelevance

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations to be appended to reach the full _count_. This behavior may be suppressed by using "medium" or "high" values. In such a case, the system only recommends items of at least the requested relevance and may return less than _count_ items when there is not enough data to fulfill it.

---

rotationRate

Number

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended items. Default: `0`.

---

rotationTime

Number

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized. Default: `7200.0`.

---

##### Responses

200

Successful operation.

```
{
  "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Recommend Items to Item

Allowed on Client-Side

Recommends a set of items that are somehow related to one given item, _X_. A typical scenario is when the user _A_ is viewing _X_. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user _A_ into account.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:

* Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics).
* Get subsequent recommended items when the user scrolls down (_infinite scroll_) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items).

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemsToItem(itemId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:default',                                             // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```kotlin
val result = client.sendAsync(RecommendItemsToItem(itemId, targetUserId, count,
    // optional parameters:
    scenario = "homepage",                                                // String
    cascadeCreate = true,                                                 // Boolean
    returnProperties = true,                                              // Boolean
    includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
    filter = "price > 50",                                                // String
    booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic = Logic(name = "recombee:default"),                             // Logic
    reqlExpressions = mapOf(
        "isInUsersCity" to "context_user[\"city\"] in 'cities'",
    ),                                                                    // Map<String, String>
    minRelevance = "low",                                                 // String
    rotationRate = 0.1,                                                   // Double
    rotationTime = 7200.0,                                                // Double
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemsToItem(itemId: itemId, targetUserId: targetUserId, count: count,
    // optional parameters:
    scenario: "homepage",                                                // String
    cascadeCreate: true,                                                 // Bool
    returnProperties: true,                                              // Bool
    includedProperties: ["title", "price", "publishedAt"],               // [String]
    filter: "price > 50",                                                // String
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic: Logic(name: "recombee:default"),                              // Logic
    reqlExpressions: [
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    ],                                                                   // JSONDictionary
    minRelevance: "low",                                                 // String
    rotationRate: 0.1,                                                   // Double
    rotationTime: 7200.0                                                 // Double
))
```

```js
const result = await client.send(new requests.RecommendItemsToItem(itemId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:default',                                             // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```python
result = client.send(RecommendItemsToItem(item_id, target_user_id, count,
    # optional parameters:
    scenario='homepage',                                                # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['title', 'price', 'publishedAt'],              # array
    filter='price > 50',                                                # string
    booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic='recombee:default',                                           # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
    min_relevance='low',                                                # string
    rotation_rate=0.1,                                                  # number
    rotation_time=7200.0,                                               # number
))
```

```ruby
result = client.send(RecommendItemsToItem.new(item_id, target_user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['title', 'price', 'publishedAt'],              # array
  filter: 'price > 50',                                                # string
  booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
  logic: 'recombee:default',                                           # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
  min_relevance: 'low',                                                # string
  rotation_rate: 0.1,                                                  # number
  rotation_time: 7200.0,                                               # number
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemsToItem(itemId, targetUserId, count)
    .setScenario("homepage")                                                // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
    .setFilter("price > 50")                                                // String
    .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
    .setLogic(new Logic("recombee:default"))                                // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
    .setMinRelevance("low")                                                 // String
    .setRotationRate(0.1)                                                   // double
    .setRotationTime(7200.0)                                                // double
);
```

```php
$result = $client->send(new Reqs\RecommendItemsToItem($item_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['title', 'price', 'publishedAt'],               // array
    'filter' => 'price > 50',                                                // string
    'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
    'minRelevance' => 'low',                                                 // string
    'rotationRate' => 0.1,                                                   // number
    'rotationTime' => 7200.0,                                                // number
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemsToItem(itemId, targetUserId, count,
    // optional parameters:
    scenario: "homepage",                                                  // string
    cascadeCreate: true,                                                   // bool
    returnProperties: true,                                                // bool
    includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
    filter: "price > 50",                                                  // string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
    logic: new Logic(name: "recombee:default"),                            // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    },                                                                     // Dictionary<string, string>
    minRelevance: "low",                                                   // string
    rotationRate: 0.1,                                                     // double
    rotationTime: 7200.0                                                   // double
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendItemsToItem(itemId, targetUserId, count).
    // optional parameters:
    SetScenario("homepage").                                                // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"title", "price", "publishedAt"}).       // []string
    SetFilter("price > 50").                                                // string
    SetBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    }).                                                                     // map[string]string
    SetMinRelevance("low").                                                 // string
    SetRotationRate(0.1).                                                   // float64
    SetRotationTime(7200.0)                                                 // float64

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/items/{itemId}/items/?targetUserId=user-1
&count=10
&scenario=homepage
&cascadeCreate=true
&returnProperties=true
&includedProperties=title,price,publishedAt
&filter=price > 50
&booster=if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1
&logic=recombee:default
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
&minRelevance=low
&rotationRate=0.1
&rotationTime=7200.0
```

---

Since version

2.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of the item for which the recommendations are to be generated.

---

targetUserId

String

Located in: **query**

Required: **Yes**

Since version: **2.0.0**

ID of the user who will see the recommendations.

Specifying the _targetUserId_ is beneficial because:

* It makes the recommendations personalized
* Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterward viewed/purchased an item.

If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the language) to _targetUserId_. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users, it is possible to use, for example, their session ID.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **2.0.0**

Number of items to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

If an item of the given _itemId_ or user of the given _targetUserId_ doesn't exist in the database, it creates the missing entity/entities and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given _targetUserId_, as the user will be already known to the system.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.

Example response:

```
  {
    "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **2.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  {
    "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **2.4.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])",
    "isFromSameCompany": "'company' == context_item[\"company\"]"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2,
          "isFromSameCompany": false
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0,
          "isFromSameCompany": true
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

minRelevance

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** If the _targetUserId_ is provided: Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full _count_. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance and may return less than _count_ items when there is not enough data to fulfill it.

---

rotationRate

Number

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** If the _targetUserId_ is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended items.

---

rotationTime

Number

Located in: **query**

Required: **No**

Since version: **2.0.0**

**Expert option:** If the _targetUserId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.

---

##### Responses

200

Successful operation.

```
{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-146"
    },
    {
      "id": "item-462"
    },
    {
      "id": "item-463"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

itemId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Recommend Items to Item Segment

Allowed on Client-Side

Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations).

Based on the used Segmentation, this endpoint can be used for example for:

* Recommending articles related to a particular topic
* Recommending songs belonging to a particular genre
* Recommending products produced by a particular brand

You need to set the used context Segmentation in the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.

The returned items are sorted by relevance (the first item being the most relevant).

It is also possible to use the POST HTTP method (for example, in the case of a very long ReQL filter) — query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:personal-from-segment',                               // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```kotlin
val result = client.sendAsync(RecommendItemsToItemSegment(contextSegmentId, targetUserId, count,
    // optional parameters:
    scenario = "homepage",                                                // String
    cascadeCreate = true,                                                 // Boolean
    returnProperties = true,                                              // Boolean
    includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
    filter = "price > 50",                                                // String
    booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic = Logic(name = "recombee:personal-from-segment"),               // Logic
    reqlExpressions = mapOf(
        "isInUsersCity" to "context_user[\"city\"] in 'cities'",
    ),                                                                    // Map<String, String>
    minRelevance = "low",                                                 // String
    rotationRate = 0.1,                                                   // Double
    rotationTime = 7200.0,                                                // Double
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemsToItemSegment(contextSegmentId: contextSegmentId, targetUserId: targetUserId, count: count,
    // optional parameters:
    scenario: "homepage",                                                // String
    cascadeCreate: true,                                                 // Bool
    returnProperties: true,                                              // Bool
    includedProperties: ["title", "price", "publishedAt"],               // [String]
    filter: "price > 50",                                                // String
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic: Logic(name: "recombee:personal-from-segment"),                // Logic
    reqlExpressions: [
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    ],                                                                   // JSONDictionary
    minRelevance: "low",                                                 // String
    rotationRate: 0.1,                                                   // Double
    rotationTime: 7200.0                                                 // Double
))
```

```js
const result = await client.send(new requests.RecommendItemsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                                  // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'recombee:personal-from-segment',                               // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
  minRelevance: 'low',                                                   // string
  rotationRate: 0.1,                                                     // number
  rotationTime: 7200.0,                                                  // number
}));
```

```python
result = client.send(RecommendItemsToItemSegment(context_segment_id, target_user_id, count,
    # optional parameters:
    scenario='homepage',                                                # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['title', 'price', 'publishedAt'],              # array
    filter='price > 50',                                                # string
    booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic='recombee:personal-from-segment',                             # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
    min_relevance='low',                                                # string
    rotation_rate=0.1,                                                  # number
    rotation_time=7200.0,                                               # number
))
```

```ruby
result = client.send(RecommendItemsToItemSegment.new(context_segment_id, target_user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['title', 'price', 'publishedAt'],              # array
  filter: 'price > 50',                                                # string
  booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
  logic: 'recombee:personal-from-segment',                             # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
  min_relevance: 'low',                                                # string
  rotation_rate: 0.1,                                                  # number
  rotation_time: 7200.0,                                               # number
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemsToItemSegment(contextSegmentId, targetUserId, count)
    .setScenario("homepage")                                                // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
    .setFilter("price > 50")                                                // String
    .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
    .setLogic(new Logic("recombee:personal-from-segment"))                  // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
    .setMinRelevance("low")                                                 // String
    .setRotationRate(0.1)                                                   // double
    .setRotationTime(7200.0)                                                // double
);
```

```php
$result = $client->send(new Reqs\RecommendItemsToItemSegment($context_segment_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['title', 'price', 'publishedAt'],               // array
    'filter' => 'price > 50',                                                // string
    'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
    'logic' => 'recombee:personal-from-segment',                             // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
    'minRelevance' => 'low',                                                 // string
    'rotationRate' => 0.1,                                                   // number
    'rotationTime' => 7200.0,                                                // number
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemsToItemSegment(contextSegmentId, targetUserId, count,
    // optional parameters:
    scenario: "homepage",                                                  // string
    cascadeCreate: true,                                                   // bool
    returnProperties: true,                                                // bool
    includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
    filter: "price > 50",                                                  // string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
    logic: new Logic(name: "recombee:personal-from-segment"),              // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    },                                                                     // Dictionary<string, string>
    minRelevance: "low",                                                   // string
    rotationRate: 0.1,                                                     // double
    rotationTime: 7200.0                                                   // double
));
```

```go
logicName := "recombee:personal-from-segment"

request := client.NewRecommendItemsToItemSegment(contextSegmentId, targetUserId, count).
    // optional parameters:
    SetScenario("homepage").                                                // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"title", "price", "publishedAt"}).       // []string
    SetFilter("price > 50").                                                // string
    SetBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    }).                                                                     // map[string]string
    SetMinRelevance("low").                                                 // string
    SetRotationRate(0.1).                                                   // float64
    SetRotationTime(7200.0)                                                 // float64

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/item-segments/items/?contextSegmentId=segment-1
&targetUserId=user-1
&count=10
&scenario=homepage
&cascadeCreate=true
&returnProperties=true
&includedProperties=title,price,publishedAt
&filter=price > 50
&booster=if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1
&logic=recombee:personal-from-segment
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
&minRelevance=low
&rotationRate=0.1
&rotationTime=7200.0
```

---

Since version

5.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **5.0.0**

ID of your database.

---

contextSegmentId

String

Located in: **query**

Required: **Yes**

Since version: **5.0.0**

ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.

---

targetUserId

String

Located in: **query**

Required: **Yes**

Since version: **5.0.0**

ID of the user who will see the recommendations.

Specifying the _targetUserId_ is beneficial because:

* It makes the recommendations personalized
* Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterward viewed/purchased an item.

If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the language) to _targetUserId_. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users, it is possible to use, for example, their session ID.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **5.0.0**

Number of items to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **5.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **5.0.0**

If a user of the given _targetUserId_ doesn't exist in the database, it creates this user and returns some (non-personalized) recommendations. This allows, for example, rotations in the following recommendations for the user of the given _targetUserId_, as the user will be already known to the system.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **5.0.0**

With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.

Example response:

```
  {
    "recommId": "0c6189e7-dc1a-429a-b613-192696309361",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **5.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  {
    "recommId": "6842c725-a79f-4537-a02c-f34d668a3f80",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **5.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **5.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **5.0.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

minRelevance

String

Located in: **query**

Required: **No**

Since version: **5.0.0**

**Expert option:** If the _targetUserId_ is provided: Specifies the threshold of how relevant must the recommended items be to the user. Possible values one of: "low", "medium", "high". The default value is "low", meaning that the system attempts to recommend a number of items equal to _count_ at any cost. If there is not enough data (such as interactions or item properties), this may even lead to bestseller-based recommendations being appended to reach the full _count_. This behavior may be suppressed by using "medium" or "high" values. In such case, the system only recommends items of at least the requested relevance and may return less than _count_ items when there is not enough data to fulfill it.

---

rotationRate

Number

Located in: **query**

Required: **No**

Since version: **5.0.0**

**Expert option:** If the _targetUserId_ is provided: If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize an item for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended items.

---

rotationTime

Number

Located in: **query**

Required: **No**

Since version: **5.0.0**

**Expert option:** If the _targetUserId_ is provided: Taking _rotationRate_ into account, specifies how long it takes for an item to recover from the penalization. For example, `rotationTime=7200.0` means that items recommended less than 2 hours ago are penalized.

---

##### Responses

200

successful operation

```
{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-176"
    },
    {
      "id": "item-141"
    },
    {
      "id": "item-967"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

count is not a positive integer.

---

404

contextSegmentId not found in the context segmentation

---

get

#### Recommend Next Items

Allowed on Client-Side

Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (_infinite scroll_) or goes to the next page.

It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (`count`). The base request can be one of:

* [Recommend Items to Item](https://docs.recombee.com/api#recommend-items-to-item)
* [Recommend Items to User](https://docs.recombee.com/api#recommend-items-to-user)
* [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)
* [Search Items](https://docs.recombee.com/api#search-items)

All the other parameters are inherited from the base request.

_Recommend next items_ can be called many times for a single `recommId` and each call returns different (previously not recommended) items. The number of _Recommend next items_ calls performed so far is returned in the `numberNextRecommsCalls` field.

_Recommend next items_ can be requested up to 30 minutes after the base request or a previous _Recommend next items_ call.

For billing purposes, each call to _Recommend next items_ is counted as a separate recommendation request.

```js
const result = await client.send(new recombee.RecommendNextItems(recommId, count));
```

```kotlin
val result = client.sendAsync(RecommendNextItems(recommId, count))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendNextItems(recommId: recommId, count: count))
```

```js
const result = await client.send(new requests.RecommendNextItems(recommId, count));
```

```python
result = client.send(RecommendNextItems(recomm_id, count))
```

```ruby
result = client.send(RecommendNextItems.new(recomm_id, count))
```

```java
RecommendationResponse result = client.send(new RecommendNextItems(recommId, count));
```

```php
$result = $client->send(new Reqs\RecommendNextItems($recomm_id, $count));
```

```csharp
RecommendationResponse result = client.Send(new RecommendNextItems(recommId, count));
```

```go
request := client.NewRecommendNextItems(recommId, count)

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/next/items/{recommId}?count=10
```

---

Since version

3.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.1.0**

ID of your database.

---

recommId

String

Located in: **path**

Required: **Yes**

Since version: **3.1.0**

ID of the base recommendation request for which next recommendations should be returned

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **3.1.0**

Number of items to be recommended

---

##### Responses

200

Successful operation.

```
{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-176"
    },
    {
      "id": "item-141"
    },
    {
      "id": "item-967"
    }
  ],
  "numberNextRecommsCalls": 4
}
```

---

400

Parameter `count` is not given or is not a positive integer. Parameter `recommId` is not an UUID.

---

404

Base request with the given `recommId` does not exist or has expired.

---

### Recommending Item Segments

Recommendation endpoints that return the [Item Segments](https://docs.recombee.com/segmentations) (categories, genres, artists, etc.).

get

#### Recommend Item Segments to User

Allowed on Client-Side

Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations) for a particular user, based on the user's past interactions.

Based on the used Segmentation, this endpoint can be used for example for:

* Recommending the top categories for the user
* Recommending the top genres for the user
* Recommending the top brands for the user
* Recommending the top artists for the user

You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemSegmentsToUser(userId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```kotlin
val result = client.sendAsync(RecommendItemSegmentsToUser(userId, count,
    // optional parameters:
    scenario = "homepage",                                                   // String
    cascadeCreate = true,                                                    // Boolean
    filter = "'segmentId' != \"coupons\"",                                   // String
    booster = "if 'segmentId' == \"Editors Pick\" then 2 else 1",            // String
    logic = Logic(name = "recombee:default"),                                // Logic
    reqlExpressions = mapOf(
        "countItems" to "size(segment_items(\"categories\", 'segmentId'))",
    ),                                                                       // Map<String, String>
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemSegmentsToUser(userId: userId, count: count,
    // optional parameters:
    scenario: "homepage",                                                  // String
    cascadeCreate: true,                                                   // Bool
    filter: "'segmentId' != \"coupons\"",                                  // String
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",           // String
    logic: Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: [
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    ]                                                                      // JSONDictionary
))
```

```js
const result = await client.send(new requests.RecommendItemSegmentsToUser(userId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```python
result = client.send(RecommendItemSegmentsToUser(user_id, count,
    # optional parameters:
    scenario='homepage',                                                   # string
    cascade_create=True,                                                   # boolean
    filter='\'segmentId\' != "coupons"',                                   # string
    booster='if \'segmentId\' == "Editors Pick" then 2 else 1',            # string
    logic='recombee:default',                                              # string / dict
    reql_expressions={
        'countItems': 'size(segment_items("categories", \'segmentId\'))',
    },                                                                     # dict
))
```

```ruby
result = client.send(RecommendItemSegmentsToUser.new(user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                  # string
  cascade_create: true,                                                  # boolean
  filter: '\'segmentId\' != "coupons"',                                  # string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',           # string
  logic: 'recombee:default',                                             # string / Hash
  reql_expressions: {
    'countItems' => 'size(segment_items("categories", \'segmentId\'))',
  },                                                                     # Hash
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemSegmentsToUser(userId, count)
    .setScenario("homepage")                                                    // String
    .setCascadeCreate(true)                                                     // boolean
    .setFilter("'segmentId' != \"coupons\"")                                    // String
    .setBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1")             // String
    .setLogic(new Logic("recombee:default"))                                    // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("countItems", "size(segment_items(\"categories\", 'segmentId'))");
    }})                                                                         // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\RecommendItemSegmentsToUser($user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'filter' => '\'segmentId\' != "coupons"',                                // string
    'booster' => 'if \'segmentId\' == "Editors Pick" then 2 else 1',         // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'countItems' => 'size(segment_items("categories", \'segmentId\'))',
    ],                                                                       // array (map)
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemSegmentsToUser(userId, count,
    // optional parameters:
    scenario: "homepage",                                                      // string
    cascadeCreate: true,                                                       // bool
    filter: "'segmentId' != \"coupons\"",                                      // string
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",               // string
    logic: new Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "countItems", "size(segment_items(\"categories\", 'segmentId'))" },
    }                                                                          // Dictionary<string, string>
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendItemSegmentsToUser(userId, count).
    // optional parameters:
    SetScenario("homepage").                                               // string
    SetCascadeCreate(true).                                                // bool
    SetFilter("'segmentId' != \"coupons\"").                               // string
    SetBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1").        // string
    SetLogic(bindings.Logic{Name: &logicName}).                            // bindings.Logic
    SetReqlExpressions(map[string]string{
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    })                                                                     // map[string]string

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/users/{userId}/item-segments/?count=10
&scenario=homepage
&cascadeCreate=true
&filter='segmentId' != "coupons"
&booster=if 'segmentId' == "Editors Pick" then 2 else 1
&logic=recombee:default
&reqlExpressions={"countItems":"size(segment_items(\"categories\", 'segmentId'))"}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the user for whom personalized recommendations are to be generated.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

Number of item segments to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **4.1.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

filter

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.

---

booster

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **4.1.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.1.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "countItems": "size(segment_items(\"categories\", 'segmentId'))"
  }
}
```

Example response:

```
{
  "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8",
  "recomms": 
    [
      {
        "id": "category-fantasy-books",
        "reqlEvaluations": {
          "countItems": 486
        }
      },
      {
        "id": "category-sci-fi-costumes",
        "reqlEvaluations": {
          "countItems": 19
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

successful operation

```
{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

Used Segmentation not configured for the scenario. userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer.

---

404

userId not found in the database and cascadeCreate is false

---

get

#### Recommend Item Segments to Item

Allowed on Client-Side

Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular item.

Based on the used Segmentation, this endpoint can be used for example for:

* Recommending the related categories
* Recommending the related genres
* Recommending the related brands
* Recommending the related artists

You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemSegmentsToItem(itemId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```kotlin
val result = client.sendAsync(RecommendItemSegmentsToItem(itemId, targetUserId, count,
    // optional parameters:
    scenario = "homepage",                                                   // String
    cascadeCreate = true,                                                    // Boolean
    filter = "'segmentId' != \"coupons\"",                                   // String
    booster = "if 'segmentId' == \"Editors Pick\" then 2 else 1",            // String
    logic = Logic(name = "recombee:default"),                                // Logic
    reqlExpressions = mapOf(
        "countItems" to "size(segment_items(\"categories\", 'segmentId'))",
    ),                                                                       // Map<String, String>
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemSegmentsToItem(itemId: itemId, targetUserId: targetUserId, count: count,
    // optional parameters:
    scenario: "homepage",                                                  // String
    cascadeCreate: true,                                                   // Bool
    filter: "'segmentId' != \"coupons\"",                                  // String
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",           // String
    logic: Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: [
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    ]                                                                      // JSONDictionary
))
```

```js
const result = await client.send(new requests.RecommendItemSegmentsToItem(itemId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```python
result = client.send(RecommendItemSegmentsToItem(item_id, target_user_id, count,
    # optional parameters:
    scenario='homepage',                                                   # string
    cascade_create=True,                                                   # boolean
    filter='\'segmentId\' != "coupons"',                                   # string
    booster='if \'segmentId\' == "Editors Pick" then 2 else 1',            # string
    logic='recombee:default',                                              # string / dict
    reql_expressions={
        'countItems': 'size(segment_items("categories", \'segmentId\'))',
    },                                                                     # dict
))
```

```ruby
result = client.send(RecommendItemSegmentsToItem.new(item_id, target_user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                  # string
  cascade_create: true,                                                  # boolean
  filter: '\'segmentId\' != "coupons"',                                  # string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',           # string
  logic: 'recombee:default',                                             # string / Hash
  reql_expressions: {
    'countItems' => 'size(segment_items("categories", \'segmentId\'))',
  },                                                                     # Hash
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemSegmentsToItem(itemId, targetUserId, count)
    .setScenario("homepage")                                                    // String
    .setCascadeCreate(true)                                                     // boolean
    .setFilter("'segmentId' != \"coupons\"")                                    // String
    .setBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1")             // String
    .setLogic(new Logic("recombee:default"))                                    // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("countItems", "size(segment_items(\"categories\", 'segmentId'))");
    }})                                                                         // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\RecommendItemSegmentsToItem($item_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'filter' => '\'segmentId\' != "coupons"',                                // string
    'booster' => 'if \'segmentId\' == "Editors Pick" then 2 else 1',         // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'countItems' => 'size(segment_items("categories", \'segmentId\'))',
    ],                                                                       // array (map)
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemSegmentsToItem(itemId, targetUserId, count,
    // optional parameters:
    scenario: "homepage",                                                      // string
    cascadeCreate: true,                                                       // bool
    filter: "'segmentId' != \"coupons\"",                                      // string
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",               // string
    logic: new Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "countItems", "size(segment_items(\"categories\", 'segmentId'))" },
    }                                                                          // Dictionary<string, string>
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendItemSegmentsToItem(itemId, targetUserId, count).
    // optional parameters:
    SetScenario("homepage").                                               // string
    SetCascadeCreate(true).                                                // bool
    SetFilter("'segmentId' != \"coupons\"").                               // string
    SetBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1").        // string
    SetLogic(bindings.Logic{Name: &logicName}).                            // bindings.Logic
    SetReqlExpressions(map[string]string{
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    })                                                                     // map[string]string

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/items/{itemId}/item-segments/?targetUserId=user-1
&count=10
&scenario=homepage
&cascadeCreate=true
&filter='segmentId' != "coupons"
&booster=if 'segmentId' == "Editors Pick" then 2 else 1
&logic=recombee:default
&reqlExpressions={"countItems":"size(segment_items(\"categories\", 'segmentId'))"}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the item for which the recommendations are to be generated.

---

targetUserId

String

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

ID of the user who will see the recommendations.

Specifying the _targetUserId_ is beneficial because:

* It makes the recommendations personalized
* Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterward viewed/purchased an item.

If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the language) to _targetUserId_. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users, it is possible to use, for example, their session ID.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

Number of item segments to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **4.1.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

filter

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.

---

booster

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **4.1.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.1.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "countItems": "size(segment_items(\"categories\", 'segmentId'))"
  }
}
```

Example response:

```
{
  "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8",
  "recomms": 
    [
      {
        "id": "category-fantasy-books",
        "reqlEvaluations": {
          "countItems": 486
        }
      },
      {
        "id": "category-sci-fi-costumes",
        "reqlEvaluations": {
          "countItems": 19
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

successful operation

```
{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

Used Segmentation not configured for the scenario. itemId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer.

---

404

itemId not found in the database and cascadeCreate is false

---

get

#### Recommend Item Segments to Item Segment

Allowed on Client-Side

Recommends Segments from a result [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular Segment from a context Segmentation.

Based on the used Segmentations, this endpoint can be used for example for:

* Recommending the related brands to particular brand
* Recommending the related brands to particular category
* Recommending the related artists to a particular genre (assuming songs are the Items)

You need to set the used context and result Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```kotlin
val result = client.sendAsync(RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count,
    // optional parameters:
    scenario = "homepage",                                                   // String
    cascadeCreate = true,                                                    // Boolean
    filter = "'segmentId' != \"coupons\"",                                   // String
    booster = "if 'segmentId' == \"Editors Pick\" then 2 else 1",            // String
    logic = Logic(name = "recombee:default"),                                // Logic
    reqlExpressions = mapOf(
        "countItems" to "size(segment_items(\"categories\", 'segmentId'))",
    ),                                                                       // Map<String, String>
))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendItemSegmentsToItemSegment(contextSegmentId: contextSegmentId, targetUserId: targetUserId, count: count,
    // optional parameters:
    scenario: "homepage",                                                  // String
    cascadeCreate: true,                                                   // Bool
    filter: "'segmentId' != \"coupons\"",                                  // String
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",           // String
    logic: Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: [
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    ]                                                                      // JSONDictionary
))
```

```js
const result = await client.send(new requests.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'recombee:default',                                         // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```python
result = client.send(RecommendItemSegmentsToItemSegment(context_segment_id, target_user_id, count,
    # optional parameters:
    scenario='homepage',                                                   # string
    cascade_create=True,                                                   # boolean
    filter='\'segmentId\' != "coupons"',                                   # string
    booster='if \'segmentId\' == "Editors Pick" then 2 else 1',            # string
    logic='recombee:default',                                              # string / dict
    reql_expressions={
        'countItems': 'size(segment_items("categories", \'segmentId\'))',
    },                                                                     # dict
))
```

```ruby
result = client.send(RecommendItemSegmentsToItemSegment.new(context_segment_id, target_user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                  # string
  cascade_create: true,                                                  # boolean
  filter: '\'segmentId\' != "coupons"',                                  # string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',           # string
  logic: 'recombee:default',                                             # string / Hash
  reql_expressions: {
    'countItems' => 'size(segment_items("categories", \'segmentId\'))',
  },                                                                     # Hash
}))
```

```java
RecommendationResponse result = client.send(new RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count)
    .setScenario("homepage")                                                    // String
    .setCascadeCreate(true)                                                     // boolean
    .setFilter("'segmentId' != \"coupons\"")                                    // String
    .setBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1")             // String
    .setLogic(new Logic("recombee:default"))                                    // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("countItems", "size(segment_items(\"categories\", 'segmentId'))");
    }})                                                                         // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\RecommendItemSegmentsToItemSegment($context_segment_id, $target_user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'filter' => '\'segmentId\' != "coupons"',                                // string
    'booster' => 'if \'segmentId\' == "Editors Pick" then 2 else 1',         // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'countItems' => 'size(segment_items("categories", \'segmentId\'))',
    ],                                                                       // array (map)
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count,
    // optional parameters:
    scenario: "homepage",                                                      // string
    cascadeCreate: true,                                                       // bool
    filter: "'segmentId' != \"coupons\"",                                      // string
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",               // string
    logic: new Logic(name: "recombee:default"),                                // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "countItems", "size(segment_items(\"categories\", 'segmentId'))" },
    }                                                                          // Dictionary<string, string>
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count).
    // optional parameters:
    SetScenario("homepage").                                               // string
    SetCascadeCreate(true).                                                // bool
    SetFilter("'segmentId' != \"coupons\"").                               // string
    SetBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1").        // string
    SetLogic(bindings.Logic{Name: &logicName}).                            // bindings.Logic
    SetReqlExpressions(map[string]string{
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    })                                                                     // map[string]string

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/item-segments/item-segments/?contextSegmentId=segment-1
&targetUserId=user-1
&count=10
&scenario=homepage
&cascadeCreate=true
&filter='segmentId' != "coupons"
&booster=if 'segmentId' == "Editors Pick" then 2 else 1
&logic=recombee:default
&reqlExpressions={"countItems":"size(segment_items(\"categories\", 'segmentId'))"}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

contextSegmentId

String

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.

---

targetUserId

String

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

ID of the user who will see the recommendations.

Specifying the _targetUserId_ is beneficial because:

* It makes the recommendations personalized
* Allows the calculation of Actions and Conversions in the graphical user interface, as Recombee can pair the user who got recommendations and who afterward viewed/purchased an item.

If you insist on not specifying the user, pass `null`(`None`, `nil`, `NULL` etc., depending on the language) to _targetUserId_. Do not create some special dummy user for getting recommendations, as it could mislead the recommendation models, and result in wrong recommendations.

For anonymous/unregistered users, it is possible to use, for example, their session ID.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

Number of item segments to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **4.1.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

filter

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.

---

booster

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **4.1.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.1.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "countItems": "size(segment_items(\"categories\", 'segmentId'))"
  }
}
```

Example response:

```
{
  "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8",
  "recomms": 
    [
      {
        "id": "category-fantasy-books",
        "reqlEvaluations": {
          "countItems": 486
        }
      },
      {
        "id": "category-sci-fi-costumes",
        "reqlEvaluations": {
          "countItems": 19
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

successful operation

```
{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

count is not a positive integer.

---

404

contextSegmentId not found in the context segmentation

---

get

#### Recommend Next Item Segments

Allowed on Client-Side

Returns [Item Segments](https://docs.recombee.com/segmentations) to be shown as the next recommendations when a user scrolls (e.g., within a carousel or feed of Item Segments such as brands, artists, topics, or categories).

The request requires the `recommId` of a base recommendation request and the number of Segments to return (`count`).

The base request can be one of:

* [Recommend Item Segments to Item](https://docs.recombee.com/api#recommend-item-segments-to-item)
* [Recommend Item Segments to User](https://docs.recombee.com/api#recommend-item-segments-to-user)
* [Recommend Item Segments to Item Segment](https://docs.recombee.com/api#recommend-item-segments-to-item-segment)
* [Search Item Segments](https://docs.recombee.com/api#search-item-segments)

All other parameters are inherited from the base request associated with the provided `recommId`.

This endpoint can be called multiple times for a single `recommId`. Each call returns different Item Segments that have not been recommended in previous calls. The number of calls made so far is returned in the `numberNextRecommsCalls` field.

Requests can be made up to 30 minutes after the base request or the most recent Recommend Next Item Segments call.

For billing purposes, each call to this endpoint is counted as a separate recommendation request.

```js
const result = await client.send(new recombee.RecommendNextItemSegments(recommId, count));
```

```kotlin
val result = client.sendAsync(RecommendNextItemSegments(recommId, count))

result.onSuccess { response: RecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: RecommendationResponse = try await client.send(RecommendNextItemSegments(recommId: recommId, count: count))
```

```js
const result = await client.send(new requests.RecommendNextItemSegments(recommId, count));
```

```python
result = client.send(RecommendNextItemSegments(recomm_id, count))
```

```ruby
result = client.send(RecommendNextItemSegments.new(recomm_id, count))
```

```java
RecommendationResponse result = client.send(new RecommendNextItemSegments(recommId, count));
```

```php
$result = $client->send(new Reqs\RecommendNextItemSegments($recomm_id, $count));
```

```csharp
RecommendationResponse result = client.Send(new RecommendNextItemSegments(recommId, count));
```

```go
request := client.NewRecommendNextItemSegments(recommId, count)

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/next/item-segments/{recommId}?count=10
```

---

Since version

6.2.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **6.2.0**

ID of your database.

---

recommId

String

Located in: **path**

Required: **Yes**

Since version: **6.2.0**

ID of the base recommendation request for which next recommendations should be returned

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **6.2.0**

Number of item segments to be recommended

---

##### Responses

200

Successful operation.

```
{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "Comedy"
    },
    {
      "id": "Drama"
    },
    {
      "id": "Action"
    }
  ],
  "numberNextRecommsCalls": 4
}
```

---

400

Parameter `count` is not given or is not a positive integer. Parameter `recommId` is not an UUID.

---

404

Base request with the given `recommId` does not exist or has expired.

---

### Recommending Users

Recommendation endpoints that return the Users.

get

#### Recommend Users to User

Gets users similar to the given user, based on the user's past interactions (purchases, ratings, etc.) and values of properties.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

The returned users are sorted by similarity (the first user being the most similar).

```js
const result = await client.send(new requests.RecommendUsersToUser(userId, count, {
  // optional parameters:
  scenario: 'homepage',                                                // string
  cascadeCreate: true,                                                 // boolean
  returnProperties: true,                                              // boolean
  includedProperties: ['username', 'country'],                         // array
  filter: '\'country\' == "US"',                                       // string
  booster: 'if \'country\' == context_user["country"] then 2 else 1',  // string
  logic: 'recombee:default',                                           // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                   // Object
  rotationRate: 0.1,                                                   // number
  rotationTime: 7200.0,                                                // number
}));
```

```python
result = client.send(RecommendUsersToUser(user_id, count,
    # optional parameters:
    scenario='homepage',                                                # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['username', 'country'],                        # array
    filter='\'country\' == "US"',                                       # string
    booster='if \'country\' == context_user["country"] then 2 else 1',  # string
    logic='recombee:default',                                           # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
    rotation_rate=0.1,                                                  # number
    rotation_time=7200.0,                                               # number
))
```

```ruby
result = client.send(RecommendUsersToUser.new(user_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['username', 'country'],                        # array
  filter: '\'country\' == "US"',                                       # string
  booster: 'if \'country\' == context_user["country"] then 2 else 1',  # string
  logic: 'recombee:default',                                           # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
  rotation_rate: 0.1,                                                  # number
  rotation_time: 7200.0,                                               # number
}))
```

```java
RecommendationResponse result = client.send(new RecommendUsersToUser(userId, count)
    .setScenario("homepage")                                                // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"username", "country"})             // String[]
    .setFilter("'country' == \"US\"")                                       // String
    .setBooster("if 'country' == context_user[\"country\"] then 2 else 1")  // String
    .setLogic(new Logic("recombee:default"))                                // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
    .setRotationRate(0.1)                                                   // double
    .setRotationTime(7200.0)                                                // double
);
```

```php
$result = $client->send(new Reqs\RecommendUsersToUser($user_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['username', 'country'],                         // array
    'filter' => '\'country\' == "US"',                                       // string
    'booster' => 'if \'country\' == context_user["country"] then 2 else 1',  // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
    'rotationRate' => 0.1,                                                   // number
    'rotationTime' => 7200.0,                                                // number
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendUsersToUser(userId, count,
    // optional parameters:
    scenario: "homepage",                                                // string
    cascadeCreate: true,                                                 // bool
    returnProperties: true,                                              // bool
    includedProperties: new string[] { "username", "country" },          // string[]
    filter: "'country' == \"US\"",                                       // string
    booster: "if 'country' == context_user[\"country\"] then 2 else 1",  // string
    logic: new Logic(name: "recombee:default"),                          // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    },                                                                   // Dictionary<string, string>
    rotationRate: 0.1,                                                   // double
    rotationTime: 7200.0                                                 // double
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendUsersToUser(userId, count).
    // optional parameters:
    SetScenario("homepage").                                                // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"username", "country"}).                 // []string
    SetFilter("'country' == \"US\"").                                       // string
    SetBooster("if 'country' == context_user[\"country\"] then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    }).                                                                     // map[string]string
    SetRotationRate(0.1).                                                   // float64
    SetRotationTime(7200.0)                                                 // float64

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/users/{userId}/users/?count=10
&scenario=homepage
&cascadeCreate=true
&returnProperties=true
&includedProperties=username,country
&filter='country' == "US"
&booster=if 'country' == context_user["country"] then 2 else 1
&logic=recombee:default
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
&rotationRate=0.1
&rotationTime=7200.0
```

---

Since version

2.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

User to whom we find similar users

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **2.0.0**

Number of users to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users.

Example response:

```
  {
    "recommId": "9cb9c55d-50ba-4478-84fd-ab456136156e",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US",
            "sex": "F"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN",
            "sex": "M"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **2.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=country`:

```
  {
    "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **2.4.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

rotationRate

Number

Located in: **query**

Required: **No**

Since version: **5.0.0**

**Expert option:** If your users browse the system in real-time, it may easily happen that you wish to offer them recommendations multiple times. Here comes the question: how much should the recommendations change? Should they remain the same, or should they rotate? Recombee API allows you to control this per request in a backward fashion. You may penalize a user for being recommended in the near past. For the specific user, `rotationRate=1` means maximal rotation, `rotationRate=0` means absolutely no rotation. You may also use, for example, `rotationRate=0.2` for only slight rotation of recommended users.

---

rotationTime

Number

Located in: **query**

Required: **No**

Since version: **5.0.0**

**Expert option:** Taking _rotationRate_ into account, specifies how long it takes for a user to recover from the penalization. For example, `rotationTime=7200.0` means that users recommended less than 2 hours ago are penalized.

---

##### Responses

200

Successful operation.

```
{
  "recommId": "f88d970d-561c-460f-b4d4-faf0478244ca",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### Recommend Users to Item

Recommends users that are likely to be interested in the given item.

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

The returned users are sorted by predicted interest in the item (the first user being the most interested).

```js
const result = await client.send(new requests.RecommendUsersToItem(itemId, count, {
  // optional parameters:
  scenario: 'homepage',                                                // string
  cascadeCreate: true,                                                 // boolean
  returnProperties: true,                                              // boolean
  includedProperties: ['username', 'country'],                         // array
  filter: '\'country\' == "US"',                                       // string
  booster: 'if \'country\' == context_user["country"] then 2 else 1',  // string
  logic: 'recombee:default',                                           // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                   // Object
}));
```

```python
result = client.send(RecommendUsersToItem(item_id, count,
    # optional parameters:
    scenario='homepage',                                                # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['username', 'country'],                        # array
    filter='\'country\' == "US"',                                       # string
    booster='if \'country\' == context_user["country"] then 2 else 1',  # string
    logic='recombee:default',                                           # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
))
```

```ruby
result = client.send(RecommendUsersToItem.new(item_id, count, {
  # optional parameters:
  scenario: 'homepage',                                                # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['username', 'country'],                        # array
  filter: '\'country\' == "US"',                                       # string
  booster: 'if \'country\' == context_user["country"] then 2 else 1',  # string
  logic: 'recombee:default',                                           # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
}))
```

```java
RecommendationResponse result = client.send(new RecommendUsersToItem(itemId, count)
    .setScenario("homepage")                                                // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"username", "country"})             // String[]
    .setFilter("'country' == \"US\"")                                       // String
    .setBooster("if 'country' == context_user[\"country\"] then 2 else 1")  // String
    .setLogic(new Logic("recombee:default"))                                // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\RecommendUsersToItem($item_id, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['username', 'country'],                         // array
    'filter' => '\'country\' == "US"',                                       // string
    'booster' => 'if \'country\' == context_user["country"] then 2 else 1',  // string
    'logic' => 'recombee:default',                                           // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
]));
```

```csharp
RecommendationResponse result = client.Send(new RecommendUsersToItem(itemId, count,
    // optional parameters:
    scenario: "homepage",                                                // string
    cascadeCreate: true,                                                 // bool
    returnProperties: true,                                              // bool
    includedProperties: new string[] { "username", "country" },          // string[]
    filter: "'country' == \"US\"",                                       // string
    booster: "if 'country' == context_user[\"country\"] then 2 else 1",  // string
    logic: new Logic(name: "recombee:default"),                          // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    }                                                                    // Dictionary<string, string>
));
```

```go
logicName := "recombee:default"

request := client.NewRecommendUsersToItem(itemId, count).
    // optional parameters:
    SetScenario("homepage").                                                // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"username", "country"}).                 // []string
    SetFilter("'country' == \"US\"").                                       // string
    SetBooster("if 'country' == context_user[\"country\"] then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    })                                                                      // map[string]string

result, err := request.Send() // result is of the type bindings.RecommendationResponse
```

```http
GET /{databaseId}/recomms/items/{itemId}/users/?count=10
&scenario=homepage
&cascadeCreate=true
&returnProperties=true
&includedProperties=username,country
&filter='country' == "US"
&booster=if 'country' == context_user["country"] then 2 else 1
&logic=recombee:default
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
```

---

Since version

2.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of your database.

---

itemId

String

Located in: **path**

Required: **Yes**

Since version: **2.0.0**

ID of the item for which the recommendations are to be generated.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **2.0.0**

Number of users to be recommended (N for the top-N recommendation).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

If an item of the given _itemId_ doesn't exist in the database, it creates the missing item.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **2.0.0**

With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended users.

Example response:

```
  {
    "recommId": "039b71dc-b9cc-4645-a84f-62b841eecfce",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US",
            "sex": "F"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN",
            "sex": "M"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **2.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=country`:

```
  {
    "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678",
    "recomms":
      [
        {
          "id": "user-17",
          "values": {
            "country": "US"
          }
        },
        {
          "id": "user-2",
          "values": {
            "country": "CAN"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **2.4.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])",
    "isFromSameCompany": "'company' == context_item[\"company\"]"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2,
          "isFromSameCompany": false
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0,
          "isFromSameCompany": true
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

Successful operation.

```
{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

itemId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

itemId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Composite Recommendations

Composite Recommendations return a source entity (e.g., an Item, or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response, enabling multi-layered, highly personalized suggestions, such as _Because You Watched …_ in streaming services or _Top Products from Your Favorite Brand …_ in e-commerce.

post

#### Composite Recommendation

Allowed on Client-Side

Composite Recommendation returns both a _source entity_ (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations)) and a list of related recommendations in a single response.

It is ideal for use cases such as personalized homepage sections (_Articles from <category>_), _Because You Watched <movie>_, or _Artists Related to Your Favorite Artist <artist>_.

See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).

**Structure**

The endpoint operates in two stages:

1. Recommends the _source_ (e.g., an Item Segment or item) to the user.
2. Recommends _results_ (items or Item Segments) related to that _source_.

For example, _Articles from <category>_ can be decomposed into:

* [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category.
* [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category.

Since the first step uses [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user), you must include the `userId` parameter in the _Composite Recommendation_ request.

Each _Composite Recommendation_ counts as a single recommendation API request for billing.

**Stage-specific Parameters**

Additional parameters can be supplied via [sourceSettings](https://docs.recombee.com/api#composite-recommendation-param-sourceSettings) and [resultSettings](https://docs.recombee.com/api#composite-recommendation-param-resultSettings). In the example above:

* `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user) (e.g., `filter`, `booster`).
* `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment).

See [this example](https://docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details.

```js
const result = await client.send(new recombee.CompositeRecommendation(scenario, count, {
  // optional parameters:
  itemId: 'item-1',                                                        // string
  userId: 'user-1',                                                        // string
  logic: 'recombee:items-from-top-segment-for-you',                        // string / Object
  segmentId: 'segment-1',                                                  // string
  searchQuery: 'shoes',                                                    // string
  cascadeCreate: true,                                                     // boolean
  sourceSettings: {
    returnProperties: true,                                                // boolean
    includedProperties: ['title', 'price', 'publishedAt'],                 // array
    filter: 'price > 50',                                                  // string
    booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
    logic: 'recombee:default',                                             // string / Object
    reqlExpressions: {
      isInUsersCity: 'context_user["city"] in \'cities\'',
    },                                                                     // Object
    minRelevance: 'low',                                                   // string
    rotationRate: 0.1,                                                     // number
    rotationTime: 7200.0,                                                  // number
  },
  resultSettings: {
    returnProperties: true,                                                // boolean
    includedProperties: ['title', 'price', 'publishedAt'],                 // array
    filter: 'price > 50',                                                  // string
    booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
    logic: 'recombee:default',                                             // string / Object
    reqlExpressions: {
      isInUsersCity: 'context_user["city"] in \'cities\'',
    },                                                                     // Object
    minRelevance: 'low',                                                   // string
    rotationRate: 0.1,                                                     // number
    rotationTime: 7200.0,                                                  // number
  },
}));
```

```kotlin
val result = client.sendAsync(CompositeRecommendation(scenario, count,
    // optional parameters:
    itemId = "item-1",                                                        // String
    userId = "user-1",                                                        // String
    logic = Logic(name = "recombee:items-from-top-segment-for-you"),          // Logic
    segmentId = "segment-1",                                                  // String
    searchQuery = "shoes",                                                    // String
    cascadeCreate = true,                                                     // Boolean
    sourceSettings = CompositeRecommendationStageParameters(
        returnProperties = true,                                              // Boolean
        includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
        filter = "price > 50",                                                // String
        booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
        logic = Logic(name = "recombee:default"),                             // Logic
        reqlExpressions = mapOf(
            "isInUsersCity" to "context_user[\"city\"] in 'cities'",
        ),                                                                    // Map<String, String>
        minRelevance = "low",                                                 // String
        rotationRate = 0.1,                                                   // Double
        rotationTime = 7200.0,                                                // Double
    ),
    resultSettings = CompositeRecommendationStageParameters(
        returnProperties = true,                                              // Boolean
        includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
        filter = "price > 50",                                                // String
        booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
        logic = Logic(name = "recombee:default"),                             // Logic
        reqlExpressions = mapOf(
            "isInUsersCity" to "context_user[\"city\"] in 'cities'",
        ),                                                                    // Map<String, String>
        minRelevance = "low",                                                 // String
        rotationRate = 0.1,                                                   // Double
        rotationTime = 7200.0,                                                // Double
    ),
))

result.onSuccess { response: CompositeRecommendationResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: CompositeRecommendationResponse = try await client.send(CompositeRecommendation(scenario: scenario, count: count,
    // optional parameters:
    itemId: "item-1",                                                        // String
    userId: "user-1",                                                        // String
    logic: Logic(name: "recombee:items-from-top-segment-for-you"),           // Logic
    segmentId: "segment-1",                                                  // String
    searchQuery: "shoes",                                                    // String
    cascadeCreate: true,                                                     // Bool
    sourceSettings: CompositeRecommendationStageParameters(
        returnProperties: true,                                              // Bool
        includedProperties: ["title", "price", "publishedAt"],               // [String]
        filter: "price > 50",                                                // String
        booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
        logic: Logic(name: "recombee:default"),                              // Logic
        reqlExpressions: [
            "isInUsersCity": "context_user[\"city\"] in 'cities'",
        ],                                                                   // JSONDictionary
        minRelevance: "low",                                                 // String
        rotationRate: 0.1,                                                   // Double
        rotationTime: 7200.0                                                 // Double
    ),
    resultSettings: CompositeRecommendationStageParameters(
        returnProperties: true,                                              // Bool
        includedProperties: ["title", "price", "publishedAt"],               // [String]
        filter: "price > 50",                                                // String
        booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
        logic: Logic(name: "recombee:default"),                              // Logic
        reqlExpressions: [
            "isInUsersCity": "context_user[\"city\"] in 'cities'",
        ],                                                                   // JSONDictionary
        minRelevance: "low",                                                 // String
        rotationRate: 0.1,                                                   // Double
        rotationTime: 7200.0                                                 // Double
    )
))
```

```js
const result = await client.send(new requests.CompositeRecommendation(scenario, count, {
  // optional parameters:
  itemId: 'item-1',                                                        // string
  userId: 'user-1',                                                        // string
  logic: 'recombee:items-from-top-segment-for-you',                        // string / Object
  segmentId: 'segment-1',                                                  // string
  searchQuery: 'shoes',                                                    // string
  cascadeCreate: true,                                                     // boolean
  sourceSettings: {
    returnProperties: true,                                                // boolean
    includedProperties: ['title', 'price', 'publishedAt'],                 // array
    filter: 'price > 50',                                                  // string
    booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
    logic: 'recombee:default',                                             // string / Object
    reqlExpressions: {
      isInUsersCity: 'context_user["city"] in \'cities\'',
    },                                                                     // Object
    minRelevance: 'low',                                                   // string
    rotationRate: 0.1,                                                     // number
    rotationTime: 7200.0,                                                  // number
  },
  resultSettings: {
    returnProperties: true,                                                // boolean
    includedProperties: ['title', 'price', 'publishedAt'],                 // array
    filter: 'price > 50',                                                  // string
    booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
    logic: 'recombee:default',                                             // string / Object
    reqlExpressions: {
      isInUsersCity: 'context_user["city"] in \'cities\'',
    },                                                                     // Object
    minRelevance: 'low',                                                   // string
    rotationRate: 0.1,                                                     // number
    rotationTime: 7200.0,                                                  // number
  },
}));
```

```python
result = client.send(CompositeRecommendation(scenario, count,
    # optional parameters:
    item_id='item-1',                                                       # string
    user_id='user-1',                                                       # string
    logic='recombee:items-from-top-segment-for-you',                        # string / dict
    segment_id='segment-1',                                                 # string
    search_query='shoes',                                                   # string
    cascade_create=True,                                                    # boolean
    source_settings=CompositeRecommendationStageParameters(
        return_properties=True,                                             # boolean
        included_properties=['title', 'price', 'publishedAt'],              # array
        filter='price > 50',                                                # string
        booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
        logic='recombee:default',                                           # string / dict
        reql_expressions={
            'isInUsersCity': 'context_user["city"] in \'cities\'',
        },                                                                  # dict
        min_relevance='low',                                                # string
        rotation_rate=0.1,                                                  # number
        rotation_time=7200.0,                                               # number
    ),
    result_settings=CompositeRecommendationStageParameters(
        return_properties=True,                                             # boolean
        included_properties=['title', 'price', 'publishedAt'],              # array
        filter='price > 50',                                                # string
        booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
        logic='recombee:default',                                           # string / dict
        reql_expressions={
            'isInUsersCity': 'context_user["city"] in \'cities\'',
        },                                                                  # dict
        min_relevance='low',                                                # string
        rotation_rate=0.1,                                                  # number
        rotation_time=7200.0,                                               # number
    ),
))
```

```ruby
result = client.send(CompositeRecommendation.new(scenario, count, {
  # optional parameters:
  item_id: 'item-1',                                                     # string
  user_id: 'user-1',                                                     # string
  logic: 'recombee:items-from-top-segment-for-you',                      # string / Hash
  segment_id: 'segment-1',                                               # string
  search_query: 'shoes',                                                 # string
  cascade_create: true,                                                  # boolean
  source_settings: CompositeRecommendationStageParameters.new(
    return_properties: true,                                             # boolean
    included_properties: ['title', 'price', 'publishedAt'],              # array
    filter: 'price > 50',                                                # string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic: 'recombee:default',                                           # string / Hash
    reql_expressions: {
      'isInUsersCity' => 'context_user["city"] in \'cities\'',
    },                                                                   # Hash
    min_relevance: 'low',                                                # string
    rotation_rate: 0.1,                                                  # number
    rotation_time: 7200.0,                                               # number
  ),
  result_settings: CompositeRecommendationStageParameters.new(
    return_properties: true,                                             # boolean
    included_properties: ['title', 'price', 'publishedAt'],              # array
    filter: 'price > 50',                                                # string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic: 'recombee:default',                                           # string / Hash
    reql_expressions: {
      'isInUsersCity' => 'context_user["city"] in \'cities\'',
    },                                                                   # Hash
    min_relevance: 'low',                                                # string
    rotation_rate: 0.1,                                                  # number
    rotation_time: 7200.0,                                               # number
  ),
}))
```

```java
CompositeRecommendationResponse result = client.send(new CompositeRecommendation(scenario, count)
    .setItemId("item-1")                                                        // String
    .setUserId("user-1")                                                        // String
    .setLogic(new Logic("recombee:items-from-top-segment-for-you"))             // Logic
    .setSegmentId("segment-1")                                                  // String
    .setSearchQuery("shoes")                                                    // String
    .setCascadeCreate(true)                                                     // boolean
    .setSourceSettings(new CompositeRecommendationStageParameters()
        .setReturnProperties(true)                                              // boolean
        .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
        .setFilter("price > 50")                                                // String
        .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
        .setLogic(new Logic("recombee:default"))                                // Logic
        .setReqlExpressions(new HashMap<String, String>() {{
            put("isInUsersCity", "context_user[\"city\"] in 'cities'");
        }})                                                                     // Map<String, String>
        .setMinRelevance("low")                                                 // String
        .setRotationRate(0.1)                                                   // double
        .setRotationTime(7200.0))                                               // double
    .setResultSettings(new CompositeRecommendationStageParameters()
        .setReturnProperties(true)                                              // boolean
        .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
        .setFilter("price > 50")                                                // String
        .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
        .setLogic(new Logic("recombee:default"))                                // Logic
        .setReqlExpressions(new HashMap<String, String>() {{
            put("isInUsersCity", "context_user[\"city\"] in 'cities'");
        }})                                                                     // Map<String, String>
        .setMinRelevance("low")                                                 // String
        .setRotationRate(0.1)                                                   // double
        .setRotationTime(7200.0))                                               // double
);
```

```php
$result = $client->send(new Reqs\CompositeRecommendation($scenario, $count, [
    // optional parameters:
    'itemId' => 'item-1',                                                        // string
    'userId' => 'user-1',                                                        // string
    'logic' => 'recombee:items-from-top-segment-for-you',                        // string / array (map)
    'segmentId' => 'segment-1',                                                  // string
    'searchQuery' => 'shoes',                                                    // string
    'cascadeCreate' => true,                                                     // boolean
    'sourceSettings' => [
        'returnProperties' => true,                                              // boolean
        'includedProperties' => ['title', 'price', 'publishedAt'],               // array
        'filter' => 'price > 50',                                                // string
        'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
        'logic' => 'recombee:default',                                           // string / array (map)
        'reqlExpressions' => [
            'isInUsersCity' => 'context_user["city"] in \'cities\'',
        ],                                                                       // array (map)
        'minRelevance' => 'low',                                                 // string
        'rotationRate' => 0.1,                                                   // number
        'rotationTime' => 7200.0,                                                // number
    ],
    'resultSettings' => [
        'returnProperties' => true,                                              // boolean
        'includedProperties' => ['title', 'price', 'publishedAt'],               // array
        'filter' => 'price > 50',                                                // string
        'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
        'logic' => 'recombee:default',                                           // string / array (map)
        'reqlExpressions' => [
            'isInUsersCity' => 'context_user["city"] in \'cities\'',
        ],                                                                       // array (map)
        'minRelevance' => 'low',                                                 // string
        'rotationRate' => 0.1,                                                   // number
        'rotationTime' => 7200.0,                                                // number
    ],
]));
```

```csharp
CompositeRecommendationResponse result = client.Send(new CompositeRecommendation(scenario, count,
    // optional parameters:
    itemId: "item-1",                                                          // string
    userId: "user-1",                                                          // string
    logic: new Logic(name: "recombee:items-from-top-segment-for-you"),         // Logic
    segmentId: "segment-1",                                                    // string
    searchQuery: "shoes",                                                      // string
    cascadeCreate: true,                                                       // bool
    sourceSettings: new CompositeRecommendationStageParameters(
        returnProperties: true,                                                // bool
        includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
        filter: "price > 50",                                                  // string
        booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
        logic: new Logic(name: "recombee:default"),                            // Logic
        reqlExpressions: new Dictionary<string, string> {
            { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
        },                                                                     // Dictionary<string, string>
        minRelevance: "low",                                                   // string
        rotationRate: 0.1,                                                     // double
        rotationTime: 7200.0                                                   // double
    ),
    resultSettings: new CompositeRecommendationStageParameters(
        returnProperties: true,                                                // bool
        includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
        filter: "price > 50",                                                  // string
        booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
        logic: new Logic(name: "recombee:default"),                            // Logic
        reqlExpressions: new Dictionary<string, string> {
            { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
        },                                                                     // Dictionary<string, string>
        minRelevance: "low",                                                   // string
        rotationRate: 0.1,                                                     // double
        rotationTime: 7200.0                                                   // double
    )
));
```

```go
logicName := "recombee:items-from-top-segment-for-you"
returnProperties := true
filter := "price > 50"
booster := "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1"
logicName2 := "recombee:default"
minRelevance := "low"
rotationRate := 0.1
rotationTime := 7200.0

request := client.NewCompositeRecommendation(scenario, count).
    // optional parameters:
    SetItemId("item-1").                                                 // string
    SetUserId("user-1").                                                 // string
    SetLogic(bindings.Logic{Name: &logicName}).                          // bindings.Logic
    SetSegmentId("segment-1").                                           // string
    SetSearchQuery("shoes").                                             // string
    SetCascadeCreate(true).                                              // bool
    SetSourceSettings(bindings.CompositeRecommendationStageParameters{
        ReturnProperties:   &returnProperties,                           // *bool
        IncludedProperties: &[]string{"title", "price", "publishedAt"},  // *[]string
        Filter:             &filter,                                     // *string
        Booster:            &booster,                                    // *string
        Logic:              bindings.Logic{Name: &logicName2},           // bindings.Logic
        ReqlExpressions:    &map[string]string{
            "isInUsersCity": "context_user[\"city\"] in 'cities'",
        },                                                               // *map[string]string
        MinRelevance:       &minRelevance,                               // *string
        RotationRate:       &rotationRate,                               // *float64
        RotationTime:       &rotationTime,                               // *float64
    }).
    SetResultSettings(bindings.CompositeRecommendationStageParameters{
        ReturnProperties:   &returnProperties,                           // *bool
        IncludedProperties: &[]string{"title", "price", "publishedAt"},  // *[]string
        Filter:             &filter,                                     // *string
        Booster:            &booster,                                    // *string
        Logic:              bindings.Logic{Name: &logicName2},           // bindings.Logic
        ReqlExpressions:    &map[string]string{
            "isInUsersCity": "context_user[\"city\"] in 'cities'",
        },                                                               // *map[string]string
        MinRelevance:       &minRelevance,                               // *string
        RotationRate:       &rotationRate,                               // *float64
        RotationTime:       &rotationTime,                               // *float64
    })

result, err := request.Send() // result is of the type bindings.CompositeRecommendationResponse
```

```http
POST /{databaseId}/recomms/composite/
Body (application/json):
{
  "scenario": "homepage",
  "count": 10,
  "itemId": "item-1",
  "userId": "user-1",
  "logic": "recombee:items-from-top-segment-for-you",
  "segmentId": "segment-1",
  "searchQuery": "shoes",
  "cascadeCreate": true,
  "sourceSettings": {
    "returnProperties": true,
    "includedProperties": [
      "title",
      "price",
      "publishedAt"
    ],
    "filter": "price > 50",
    "booster": "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",
    "logic": "recombee:default",
    "reqlExpressions": {
      "isInUsersCity": "context_user[\"city\"] in 'cities'"
    },
    "minRelevance": "low",
    "rotationRate": 0.1,
    "rotationTime": 7200.0
  },
  "resultSettings": {
    "returnProperties": true,
    "includedProperties": [
      "title",
      "price",
      "publishedAt"
    ],
    "filter": "price > 50",
    "booster": "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",
    "logic": "recombee:default",
    "reqlExpressions": {
      "isInUsersCity": "context_user[\"city\"] in 'cities'"
    },
    "minRelevance": "low",
    "rotationRate": 0.1,
    "rotationTime": 7200.0
  }
}
```

---

Since version

6.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **6.0.0**

ID of your database.

---

scenario

String

Located in: **body**

Required: **Yes**

Since version: **6.0.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

count

Integer

Located in: **body**

Required: **Yes**

Since version: **6.0.0**

Number of items to be recommended (N for the top-N recommendation).

---

itemId

String

Located in: **body**

Required: **No**

Since version: **6.0.0**

ID of the item for which the recommendations are to be generated.

---

userId

String

Located in: **body**

Required: **No**

Since version: **6.0.0**

ID of the user for which the recommendations are to be generated.

---

logic

String

Object

Located in: **body**

Required: **No**

Since version: **6.0.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

segmentId

String

Located in: **body**

Required: **No**

Since version: **6.0.0**

ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.

---

searchQuery

String

Located in: **body**

Required: **No**

Since version: **6.2.0**

Search query provided by the user. It is used for the full-text search. Only applicable if the _scenario_ corresponds to a search scenario.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Since version: **6.0.0**

If the entity for the source recommendation does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that entity, as the entity will be already known to the system.

---

sourceSettings

Object

Located in: **body**

Required: **No**

Since version: **6.0.0**

Parameters applied for recommending the _Source_ stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the _Source_.

---

resultSettings

Object

Located in: **body**

Required: **No**

Since version: **6.0.0**

Parameters applied for recommending the _Result_ stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the _Result_.

---

##### Responses

200

Successful operation.

```
{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "source": {
    "id": "category-4"
  },
  "recomms": [
    {
      "id": "item-64"
    },
    {
      "id": "item-42"
    },
    {
      "id": "item-23"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

Count is not a positive integer, provided scenario not found.

---

404

contextSegmentId not found in the context segmentation, userId not found in the database and cascadeCreate is false, itemId not found in the database and cascadeCreate is false.

---

##### Examples

###### Example Category Sections With Reordering

Suppose you want to recommend three category sections on the homepage, but in a personalized order for each user.  
For example, in a news domain, one user might see _Politics–Culture–Technology_, while another might get _Sport–Technology–Politics_.

You can achieve this by calling three Composite Recommendations within a single [Batch](https://docs.recombee.com/api#batch) request — retrieving both the personalized categories and the recommended items within each.

The Batch ensures that three distinct categories are returned in the results.

Example response:

```
[
  {
    "code": 200,
    "json": {
      "recommId": "c8f25d2a-5c39-4c45-b42b-6a7d4e6b1c52",
      "source": { "id": "category-sport" },
      "recomms": [
        { "id": "article-1024" },
        { "id": "article-2031" },
        { "id": "article-3042" }
      ],
      "numberNextRecommsCalls": 0
    }
  },
  {
    "code": 200,
    "json": {
      "recommId": "b31f16e2-f4e9-43e8-b22f-9da78a5e8e33",
      "source": { "id": "category-technology" },
      "recomms": [
        { "id": "article-501" },
        { "id": "article-507" },
        { "id": "article-519" }
      ],
      "numberNextRecommsCalls": 0
    }
  },
  {
    "code": 200,
    "json": {
      "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
      "source": { "id": "category-politics" },
      "recomms": [
        { "id": "article-146" },
        { "id": "article-462" },
        { "id": "article-463" }
      ],
      "numberNextRecommsCalls": 0
    }
  }
]
```

Requesting recommendations:

```js
const batchRequest = new recombee.Batch([
  new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId }),
  new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId }),
  new recombee.CompositeRecommendation('homepage-category-section', 6, { userId: userId })
], {
  distinctRecomms: true
});

const responses = await client.send(batchRequest);
```

```kotlin
val requests = listOf(
    CompositeRecommendation(scenario = "homepage-category-section", count = 6, userId = userId),
    CompositeRecommendation(scenario = "homepage-category-section", count = 6, userId = userId),
    CompositeRecommendation(scenario = "homepage-category-section", count = 6, userId = userId)
)

val responses = client.send(Batch(requests = requests, distinctRecomms = true))
```

```swift
let requests: [any Request] = [
    CompositeRecommendation(scenario: "homepage-category-section", count: 6, userId: userId),
    CompositeRecommendation(scenario: "homepage-category-section", count: 6, userId: userId),
    CompositeRecommendation(scenario: "homepage-category-section", count: 6, userId: userId)
]

let batchRequest = Batch(requests: requests, distinctRecomms: true)
let result = try await client.send(batchRequest)
```

```python
reqs = [
  CompositeRecommendation("homepage-category-section", 6, user_id=user_id),
  CompositeRecommendation("homepage-category-section", 6, user_id=user_id),
  CompositeRecommendation("homepage-category-section", 6, user_id=user_id),
]

responses = client.send(Batch(reqs, distinct_recomms=True))
```

```ruby
batch = Batch.new([
  CompositeRecommendation.new('homepage-category-section', 6, {:user_id => user_id}),
  CompositeRecommendation.new('homepage-category-section', 6, {:user_id => user_id}),
  CompositeRecommendation.new('homepage-category-section', 6, {:user_id => user_id})
], distinct_recomms: true)

responses = client.send(batch)
```

```java
Request[] requests = new Request[] {
  new CompositeRecommendation("homepage-category-section", 6).setUserId(userId),
  new CompositeRecommendation("homepage-category-section", 6).setUserId(userId),
  new CompositeRecommendation("homepage-category-section", 6).setUserId(userId)
};

Batch batch = new Batch(requests).setDistinctRecomms(true);
BatchResponse[] responses = client.send(batch);
```

```js
const batch = new rqs.Batch([
  new rqs.CompositeRecommendation('homepage-category-section', 6, { userId: userId }),
  new rqs.CompositeRecommendation('homepage-category-section', 6, { userId: userId }),
  new rqs.CompositeRecommendation('homepage-category-section', 6, { userId: userId })
], {
  distinctRecomms: true
});

const responses = await client.send(batch);
```

```php
$reqs = [
  new Reqs\CompositeRecommendation("homepage-category-section", 6, ["userId" => $userId]),
  new Reqs\CompositeRecommendation("homepage-category-section", 6, ["userId" => $userId]),
  new Reqs\CompositeRecommendation("homepage-category-section", 6, ["userId" => $userId]),
];

$batch = new Reqs\Batch($reqs, ["distinctRecomms" => true]);
$responses = $client->send($batch);
```

```csharp
Request[] requests = new Request[] {
  new CompositeRecommendation("homepage-category-section", 6, userId: userId),
  new CompositeRecommendation("homepage-category-section", 6, userId: userId),
  new CompositeRecommendation("homepage-category-section", 6, userId: userId)
};

BatchResponse batchResponse =
    await client.SendAsync(new Batch(requests, distinctRecomms: true));
```

```go
import (
  "github.com/recombee/go-api-client/v6/recombee/requests"
)

reqs := []requests.Request{
  requests.NewCompositeRecommendation("homepage-category-section", 6).SetUserId(userId),
  requests.NewCompositeRecommendation("homepage-category-section", 6).SetUserId(userId),
  requests.NewCompositeRecommendation("homepage-category-section", 6).SetUserId(userId),
}

batchRes, err := client.NewBatch(reqs).SetDistinctRecomms(true).Send()
```

```http
{
  "requests": [
    {
      "method": "POST",
      "path": "/recomms/composite/",
      "body": { "scenario": "homepage-category-section", "count": 6, "userId": "user-123" }
    },
    {
      "method": "POST",
      "path": "/recomms/composite/",
      "body": { "scenario": "homepage-category-section", "count": 6, "userId": "user-123" }
    },
    {
      "method": "POST",
      "path": "/recomms/composite/",
      "body": { "scenario": "homepage-category-section", "count": 6, "userId": "user-123" }
    }
  ],
  "distinctRecomms": true
}
```

---

###### Example Setting Parameters For Individual Stages

This example shows how to use parameters on both stages:

* In `sourceSettings`, we enable rotation so the _source_ changes over time for the same user.
* In `resultSettings`, we filter out promotions and return basic properties for rendering.

Example response (truncated) with `returnProperties=true` on results:

```
{
  "recommId": "7b8d0f5e-42a4-4a71-b2b7-25f9c0cc0e9a",
  "source": { "id": "article-389" },
  "recomms": [
    {
      "id": "article-1024",
      "values": { "title": "5 Books That Will Change How You Think", "url": "newsportal.com/a/1024" }
    },
    {
      "id": "article-2031",
      "values": { "title": "The Psychology of Habit Formation", "url": "newsportal.com/a/2031" }
    }
  ],
  "numberNextRecommsCalls": 0
}
```

Requesting recommendations:

```js
const req = new recombee.CompositeRecommendation(
  'because-you-read',
  10,
  {
    userId: userId,
    sourceSettings: {
      rotationRate: 0.5,
      rotationTime: 7200
    },
    resultSettings: {
      filter: "'type' != \"promotion\"",
      returnProperties: true,
      includedProperties: ['title', 'url']
    }
  }
);

const response = await client.send(req);
```

```kotlin
val req = CompositeRecommendation(
    scenario = "because-you-read",
    count = 10,
    userId = userId,
    sourceSettings = CompositeRecommendationStageParameters(
        rotationRate = 0.5,
        rotationTime = 7200.0
    ),
    resultSettings = CompositeRecommendationStageParameters(
        filter = "'type' != \"promotion\"",
        returnProperties = true,
        includedProperties = listOf("title", "url")
    )
)

val resp = client.send(req)
```

```swift
let req = CompositeRecommendation(
    scenario: "because-you-read",
    count: 10,
    userId: userId,
    sourceSettings: CompositeRecommendationStageParameters(
        rotationRate: 0.5,
        rotationTime: 7200
    ),
    resultSettings: CompositeRecommendationStageParameters(
        returnProperties: true,
        includedProperties: ["title", "url"],
        filter: "'type' != \"promotion\""
    )
)

let result = try await client.send(req)
```

```python
req = CompositeRecommendation(
    "because-you-read",
    10,
    user_id=user_id,
    source_settings=CompositeRecommendationStageParameters(
        rotation_rate=0.5,
        rotation_time=7200,
        return_properties=True
    ),
    result_settings=CompositeRecommendationStageParameters(
        filter="'type' != \"promotion\"",
        return_properties=True,
        included_properties=["title", "url"]
    ),
)

response = client.send(req)
```

```ruby
req = CompositeRecommendation.new(
  'because-you-read', 10,
  {
    :user_id => user_id,
    :source_settings => CompositeRecommendationStageParameters.new(
      :rotation_rate => 0.5,
      :rotation_time => 7200,
      :return_properties => true
    ),
    :result_settings => CompositeRecommendationStageParameters.new(
      :filter => "'type' != \"promotion\"",
      :return_properties => true,
      :included_properties => ['title', 'url']
    )
  }
)

response = client.send(req)
```

```java
CompositeRecommendation req =
    new CompositeRecommendation("because-you-read", 10)
        .setUserId(userId)
        .setSourceSettings(
            new CompositeRecommendationStageParameters()
                .setRotationRate(0.5)
                .setRotationTime(7200.0))
        .setResultSettings(
            new CompositeRecommendationStageParameters()
                .setFilter("'type' != \"promotion\"")
                .setReturnProperties(true)
                .setIncludedProperties(Arrays.asList("title", "url")));

BatchResponse resp = client.send(req);
```

```js
const req = new rqs.CompositeRecommendation(
  'because-you-read',
  10,
  {
    userId,
    sourceSettings: {
      rotationRate: 0.5,
      rotationTime: 7200
    },
    resultSettings: {
      filter: "'type' != \"promotion\"",
      returnProperties: true,
      includedProperties: ['title', 'url']
    }
  }
);

const response = await client.send(req);
```

```php
$req = new Reqs\CompositeRecommendation(
  "because-you-read",
  10,
  [
    "userId" => $userId,
    "sourceSettings" => [
      "rotationRate" => 0.5,
      "rotationTime" => 7200,
      "returnProperties" => true
    ],
    "resultSettings" => [
      "filter" => "'type' != \"promotion\"",
      "returnProperties" => true,
      "includedProperties" => ["title", "url"]
    ]
  ]
);

$response = $client->send($req);
```

```csharp
var req = new CompositeRecommendation(
    "because-you-read",
    10,
    userId: userId,
    sourceSettings: new CompositeRecommendationStageParameters(
        rotationRate: 0.5,
        rotationTime: 7200
    ),
    resultSettings: new CompositeRecommendationStageParameters(
        filter: "'type' != \"promotion\"",
        returnProperties: true,
        includedProperties: new[] { "title", "url" }
    )
);

var response = await client.SendAsync(req);
```

```go
import (
  "github.com/recombee/go-api-client/v6/recombee/bindings"
)

req := client.NewCompositeRecommendation("because-you-read", 10).SetUserId(userId)

// Source settings (pointers required for optional fields)
rot := 0.5
rt := 7200.0
rp := true
src := bindings.CompositeRecommendationStageParameters{
  ReturnProperties: &rp,
  RotationRate:     &rot,
  RotationTime:     &rt,
}
req = req.SetSourceSettings(src)

// Result settings
filter := "'type' != \"promotion\""
incl := []string{"title", "url"}
res := bindings.CompositeRecommendationStageParameters{
  Filter:             &filter,
  ReturnProperties:   &rp,
  IncludedProperties: &incl,
}
req = req.SetResultSettings(res)

resp, err := req.Send()
```

```http
{
  "method": "POST",
  "path": "/recomms/composite/",
  "body": {
    "scenario": "because-you-read",
    "count": 10,
    "userId": "user-123",
    "sourceSettings": {
      "rotationRate": 0.5,
      "rotationTime": 7200
    },
    "resultSettings": {
      "filter": "'type' != \"promotion\"",
      "returnProperties": true,
      "includedProperties": ["title", "url"]
    }
  }
}
```

## Search

Full-text personalized search. The results are based on the full-text matching of a search query and the preferences of a particular user.

get

#### Search Items

Allowed on Client-Side

Full-text personalized search. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.) with the items (items more suitable for the user are preferred in the results).

All the string and set item properties are indexed by the search engine.

This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query.

The returned items are sorted by relevance (the first item being the most relevant).

Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to:

* Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics).
* Get subsequent search results when the user scrolls down or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items).

It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.SearchItems(userId, searchQuery, count, {
  // optional parameters:
  scenario: 'search-bar',                                                // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'search:personalized',                                          // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
}));
```

```kotlin
val result = client.sendAsync(SearchItems(userId, searchQuery, count,
    // optional parameters:
    scenario = "search-bar",                                              // String
    cascadeCreate = true,                                                 // Boolean
    returnProperties = true,                                              // Boolean
    includedProperties = listOf("title", "price", "publishedAt"),         // List<String>
    filter = "price > 50",                                                // String
    booster = "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic = Logic(name = "search:personalized"),                          // Logic
    reqlExpressions = mapOf(
        "isInUsersCity" to "context_user[\"city\"] in 'cities'",
    ),                                                                    // Map<String, String>
))

result.onSuccess { response: SearchResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: SearchResponse = try await client.send(SearchItems(userId: userId, searchQuery: searchQuery, count: count,
    // optional parameters:
    scenario: "search-bar",                                              // String
    cascadeCreate: true,                                                 // Bool
    returnProperties: true,                                              // Bool
    includedProperties: ["title", "price", "publishedAt"],               // [String]
    filter: "price > 50",                                                // String
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // String
    logic: Logic(name: "search:personalized"),                           // Logic
    reqlExpressions: [
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    ]                                                                    // JSONDictionary
))
```

```js
const result = await client.send(new requests.SearchItems(userId, searchQuery, count, {
  // optional parameters:
  scenario: 'search-bar',                                                // string
  cascadeCreate: true,                                                   // boolean
  returnProperties: true,                                                // boolean
  includedProperties: ['title', 'price', 'publishedAt'],                 // array
  filter: 'price > 50',                                                  // string
  booster: 'if now() - \'publishedAt\' <= 7 * 24 * 3600 then 2 else 1',  // string
  logic: 'search:personalized',                                          // string / Object
  reqlExpressions: {
    isInUsersCity: 'context_user["city"] in \'cities\'',
  },                                                                     // Object
}));
```

```python
result = client.send(SearchItems(user_id, search_query, count,
    # optional parameters:
    scenario='search-bar',                                              # string
    cascade_create=True,                                                # boolean
    return_properties=True,                                             # boolean
    included_properties=['title', 'price', 'publishedAt'],              # array
    filter='price > 50',                                                # string
    booster="if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
    logic='search:personalized',                                        # string / dict
    reql_expressions={
        'isInUsersCity': 'context_user["city"] in \'cities\'',
    },                                                                  # dict
))
```

```ruby
result = client.send(SearchItems.new(user_id, search_query, count, {
  # optional parameters:
  scenario: 'search-bar',                                              # string
  cascade_create: true,                                                # boolean
  return_properties: true,                                             # boolean
  included_properties: ['title', 'price', 'publishedAt'],              # array
  filter: 'price > 50',                                                # string
  booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  # string
  logic: 'search:personalized',                                        # string / Hash
  reql_expressions: {
    'isInUsersCity' => 'context_user["city"] in \'cities\'',
  },                                                                   # Hash
}))
```

```java
SearchResponse result = client.send(new SearchItems(userId, searchQuery, count)
    .setScenario("search-bar")                                              // String
    .setCascadeCreate(true)                                                 // boolean
    .setReturnProperties(true)                                              // boolean
    .setIncludedProperties(new String[]{"title", "price", "publishedAt"})   // String[]
    .setFilter("price > 50")                                                // String
    .setBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1")  // String
    .setLogic(new Logic("search:personalized"))                             // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("isInUsersCity", "context_user[\"city\"] in 'cities'");
    }})                                                                     // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\SearchItems($user_id, $search_query, $count, [
    // optional parameters:
    'scenario' => 'search-bar',                                              // string
    'cascadeCreate' => true,                                                 // boolean
    'returnProperties' => true,                                              // boolean
    'includedProperties' => ['title', 'price', 'publishedAt'],               // array
    'filter' => 'price > 50',                                                // string
    'booster' => "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",  // string
    'logic' => 'search:personalized',                                        // string / array (map)
    'reqlExpressions' => [
        'isInUsersCity' => 'context_user["city"] in \'cities\'',
    ],                                                                       // array (map)
]));
```

```csharp
SearchResponse result = client.Send(new SearchItems(userId, searchQuery, count,
    // optional parameters:
    scenario: "search-bar",                                                // string
    cascadeCreate: true,                                                   // bool
    returnProperties: true,                                                // bool
    includedProperties: new string[] { "title", "price", "publishedAt" },  // string[]
    filter: "price > 50",                                                  // string
    booster: "if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1",    // string
    logic: new Logic(name: "search:personalized"),                         // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "isInUsersCity", "context_user[\"city\"] in 'cities'" },
    }                                                                      // Dictionary<string, string>
));
```

```go
logicName := "search:personalized"

request := client.NewSearchItems(userId, searchQuery, count).
    // optional parameters:
    SetScenario("search-bar").                                              // string
    SetCascadeCreate(true).                                                 // bool
    SetReturnProperties(true).                                              // bool
    SetIncludedProperties([]string{"title", "price", "publishedAt"}).       // []string
    SetFilter("price > 50").                                                // string
    SetBooster("if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1").  // string
    SetLogic(bindings.Logic{Name: &logicName}).                             // bindings.Logic
    SetReqlExpressions(map[string]string{
        "isInUsersCity": "context_user[\"city\"] in 'cities'",
    })                                                                      // map[string]string

result, err := request.Send() // result is of the type bindings.SearchResponse
```

```http
GET /{databaseId}/search/users/{userId}/items/?searchQuery=shoes
&count=10
&scenario=search-bar
&cascadeCreate=true
&returnProperties=true
&includedProperties=title,price,publishedAt
&filter=price > 50
&booster=if now() - 'publishedAt' <= 7 * 24 * 3600 then 2 else 1
&logic=search:personalized
&reqlExpressions={"isInUsersCity":"context_user[\"city\"] in 'cities'"}
```

---

Since version

3.0.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.0.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **3.0.0**

ID of the user for whom personalized search will be performed.

---

searchQuery

String

Located in: **query**

Required: **Yes**

Since version: **3.0.0**

Search query provided by the user. It is used for the full-text search.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **3.0.0**

Number of items to be returned (N for the top-N results).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **3.0.0**

Scenario defines a particular search field in your user interface.

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each field performs.

The AI that optimizes models to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **3.0.0**

If the user does not exist in the database, returns a list of non-personalized search results and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

returnProperties

Boolean

Located in: **query**

Required: **No**

Since version: **3.0.0**

With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used to easily display the recommended items to the user.

Example response:

```
  {
    "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "categories":   ["Electronics", "Televisions"],
            "price": 342,
            "url": "myshop.com/tv-178"
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "categories":   ["Home & Kitchen"],
            "price": 39,
            "url": "myshop.com/mixer-42"
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

includedProperties

Array

Located in: **query**

Required: **No**

Since version: **3.0.0**

Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list.

Example response for `includedProperties=description,price`:

```
  {
    "recommId": "a86ee8d5-cd8e-46d1-886c-8b3771d0520b",
    "recomms":
      [
        {
          "id": "tv-178",
          "values": {
            "description": "4K TV with 3D feature",
            "price": 342
          }
        },
        {
          "id": "mixer-42",
          "values": {
            "description": "Stainless Steel Mixer",
            "price": 39
          }
        }
      ],
    "numberNextRecommsCalls": 0
  }
```

---

filter

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

booster

String

Located in: **query**

Required: **No**

Since version: **2.0.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes.

Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **2.4.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.0.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "isInUsersCity": "context_user[\"city\"] in 'cities'",
    "distanceToUser": "earth_distance('location', context_user[\"location\"])"
  }
}
```

Example response:

```
{
  "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837",
  "recomms": 
    [
      {
        "id": "restaurant-178",
        "reqlEvaluations": {
          "isInUsersCity": true,
          "distanceToUser": 5200.2
        }
      },
      {
        "id": "bar-42",
        "reqlEvaluations": {
          "isInUsersCity": false,
          "distanceToUser": 2516.0
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

Successful operation.

```
{
  "recommId": "4fd901fe-4ba1-a3f1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-476"
    },
    {
      "id": "item-412"
    },
    {
      "id": "item-773"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, searchQuery is not provided, filter or booster are not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in you URL.

---

get

#### Search Item Segments

Allowed on Client-Side

Full-text personalized search that returns Segments from a Segmentation. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.).

Based on the used Segmentation, this endpoint can be used for example for:

* Searching within categories or brands
* Searching within genres or artists

For example if the user is searching for "iPhone" this endpoint can return "cell phones" category.

You need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.

The returned segments are sorted by relevance (first segment being the most relevant).

It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.

```js
const result = await client.send(new recombee.SearchItemSegments(userId, searchQuery, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'search:personalized',                                      // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```kotlin
val result = client.sendAsync(SearchItemSegments(userId, searchQuery, count,
    // optional parameters:
    scenario = "homepage",                                                   // String
    cascadeCreate = true,                                                    // Boolean
    filter = "'segmentId' != \"coupons\"",                                   // String
    booster = "if 'segmentId' == \"Editors Pick\" then 2 else 1",            // String
    logic = Logic(name = "search:personalized"),                             // Logic
    reqlExpressions = mapOf(
        "countItems" to "size(segment_items(\"categories\", 'segmentId'))",
    ),                                                                       // Map<String, String>
))

result.onSuccess { response: SearchResponse ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: SearchResponse = try await client.send(SearchItemSegments(userId: userId, searchQuery: searchQuery, count: count,
    // optional parameters:
    scenario: "homepage",                                                  // String
    cascadeCreate: true,                                                   // Bool
    filter: "'segmentId' != \"coupons\"",                                  // String
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",           // String
    logic: Logic(name: "search:personalized"),                             // Logic
    reqlExpressions: [
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    ]                                                                      // JSONDictionary
))
```

```js
const result = await client.send(new requests.SearchItemSegments(userId, searchQuery, count, {
  // optional parameters:
  scenario: 'homepage',                                              // string
  cascadeCreate: true,                                               // boolean
  filter: '\'segmentId\' != "coupons"',                              // string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',       // string
  logic: 'search:personalized',                                      // string / Object
  reqlExpressions: {
    countItems: 'size(segment_items("categories", \'segmentId\'))',
  },                                                                 // Object
}));
```

```python
result = client.send(SearchItemSegments(user_id, search_query, count,
    # optional parameters:
    scenario='homepage',                                                   # string
    cascade_create=True,                                                   # boolean
    filter='\'segmentId\' != "coupons"',                                   # string
    booster='if \'segmentId\' == "Editors Pick" then 2 else 1',            # string
    logic='search:personalized',                                           # string / dict
    reql_expressions={
        'countItems': 'size(segment_items("categories", \'segmentId\'))',
    },                                                                     # dict
))
```

```ruby
result = client.send(SearchItemSegments.new(user_id, search_query, count, {
  # optional parameters:
  scenario: 'homepage',                                                  # string
  cascade_create: true,                                                  # boolean
  filter: '\'segmentId\' != "coupons"',                                  # string
  booster: 'if \'segmentId\' == "Editors Pick" then 2 else 1',           # string
  logic: 'search:personalized',                                          # string / Hash
  reql_expressions: {
    'countItems' => 'size(segment_items("categories", \'segmentId\'))',
  },                                                                     # Hash
}))
```

```java
SearchResponse result = client.send(new SearchItemSegments(userId, searchQuery, count)
    .setScenario("homepage")                                                    // String
    .setCascadeCreate(true)                                                     // boolean
    .setFilter("'segmentId' != \"coupons\"")                                    // String
    .setBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1")             // String
    .setLogic(new Logic("search:personalized"))                                 // Logic
    .setReqlExpressions(new HashMap<String, String>() {{
        put("countItems", "size(segment_items(\"categories\", 'segmentId'))");
    }})                                                                         // Map<String, String>
);
```

```php
$result = $client->send(new Reqs\SearchItemSegments($user_id, $search_query, $count, [
    // optional parameters:
    'scenario' => 'homepage',                                                // string
    'cascadeCreate' => true,                                                 // boolean
    'filter' => '\'segmentId\' != "coupons"',                                // string
    'booster' => 'if \'segmentId\' == "Editors Pick" then 2 else 1',         // string
    'logic' => 'search:personalized',                                        // string / array (map)
    'reqlExpressions' => [
        'countItems' => 'size(segment_items("categories", \'segmentId\'))',
    ],                                                                       // array (map)
]));
```

```csharp
SearchResponse result = client.Send(new SearchItemSegments(userId, searchQuery, count,
    // optional parameters:
    scenario: "homepage",                                                      // string
    cascadeCreate: true,                                                       // bool
    filter: "'segmentId' != \"coupons\"",                                      // string
    booster: "if 'segmentId' == \"Editors Pick\" then 2 else 1",               // string
    logic: new Logic(name: "search:personalized"),                             // Logic
    reqlExpressions: new Dictionary<string, string> {
        { "countItems", "size(segment_items(\"categories\", 'segmentId'))" },
    }                                                                          // Dictionary<string, string>
));
```

```go
logicName := "search:personalized"

request := client.NewSearchItemSegments(userId, searchQuery, count).
    // optional parameters:
    SetScenario("homepage").                                               // string
    SetCascadeCreate(true).                                                // bool
    SetFilter("'segmentId' != \"coupons\"").                               // string
    SetBooster("if 'segmentId' == \"Editors Pick\" then 2 else 1").        // string
    SetLogic(bindings.Logic{Name: &logicName}).                            // bindings.Logic
    SetReqlExpressions(map[string]string{
        "countItems": "size(segment_items(\"categories\", 'segmentId'))",
    })                                                                     // map[string]string

result, err := request.Send() // result is of the type bindings.SearchResponse
```

```http
GET /{databaseId}/search/users/{userId}/item-segments/?searchQuery=shoes
&count=10
&scenario=homepage
&cascadeCreate=true
&filter='segmentId' != "coupons"
&booster=if 'segmentId' == "Editors Pick" then 2 else 1
&logic=search:personalized
&reqlExpressions={"countItems":"size(segment_items(\"categories\", 'segmentId'))"}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

userId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the user for whom personalized search will be performed.

---

searchQuery

String

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

Search query provided by the user. It is used for the full-text search.

---

count

Integer

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

Number of segments to be returned (N for the top-N results).

---

scenario

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing".

You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs.

The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.

---

cascadeCreate

Boolean

Located in: **query**

Required: **No**

Since version: **4.1.0**

If the user does not exist in the database, returns a list of non-personalized recommendations and creates the user in the database. This allows, for example, rotations in the following recommendations for that user, as the user will be already known to the system.

---

filter

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.

---

booster

String

Located in: **query**

Required: **No**

Since version: **4.1.0**

Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`.

---

logic

String

Object

Located in: **query**

Required: **No**

Since version: **4.1.0**

Logic specifies the particular behavior of the recommendation models. You can pick tailored logic for your domain and use case. See [this section](https://docs.recombee.com/recommendation_logics) for a list of available logics and other details.

The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users.

Logic can also be set to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).

---

reqlExpressions

Object

Located in: **query**

Required: **No**

Since version: **6.1.0**

A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments.

The keys are the names of the expressions, and the values are the actual ReQL expressions.

Example request:

```
{
  "reqlExpressions": {
    "countItems": "size(segment_items(\"categories\", 'segmentId'))"
  }
}
```

Example response:

```
{
  "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8",
  "recomms": 
    [
      {
        "id": "category-fantasy-books",
        "reqlEvaluations": {
          "countItems": 486
        }
      },
      {
        "id": "category-sci-fi-costumes",
        "reqlEvaluations": {
          "countItems": 19
        }
      }
    ],
   "numberNextRecommsCalls": 0
}
```

---

##### Responses

200

successful operation

```
{
  "recommId": "7acdc8b5-f731-44f8-b522-72625044666f",
  "recomms": [
    {
      "id": "cell phones"
    },
    {
      "id": "cell phone accessories"
    }
  ],
  "numberNextRecommsCalls": 0
}
```

---

400

userId does not match ^\[a-zA-Z0-9\_-:@.\]+$, count is not a positive integer, searchQuery is not provided, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer.

---

404

userId not found in the database and cascadeCreate is false. If there is no additional info in the JSON response, you probably have an error in your URL.

---

### Synonyms

Define that some words or phrases should be considered equal by the full-text search engine.

post

#### Add Search Synonym

Adds a new synonym for the [Search items](https://docs.recombee.com/api#search-items).

When the `term` is used in the search query, the `synonym` is also used for the full-text search. Unless `oneWay=true`, it works also in the opposite way (`synonym` \-> `term`).

An example of a synonym can be `science fiction` for the term `sci-fi`.

```js
const result = await client.send(new requests.AddSearchSynonym(term, synonym, {
  // optional parameters:
  oneWay: false,  // boolean
}));
```

```python
result = client.send(AddSearchSynonym(term, synonym,
    # optional parameters:
    one_way=False,  # boolean
))
```

```ruby
result = client.send(AddSearchSynonym.new(term, synonym, {
  # optional parameters:
  one_way: false,  # boolean
}))
```

```java
SearchSynonym result = client.send(new AddSearchSynonym(term, synonym)
    .setOneWay(false)  // boolean
);
```

```php
$result = $client->send(new Reqs\AddSearchSynonym($term, $synonym, [
    // optional parameters:
    'oneWay' => false,  // boolean
]));
```

```csharp
SearchSynonym result = client.Send(new AddSearchSynonym(term, synonym,
    // optional parameters:
    oneWay: false  // bool
));
```

```go
request := client.NewAddSearchSynonym(term, synonym).
    // optional parameters:
    SetOneWay(false)  // bool

result, err := request.Send() // result is of the type bindings.SearchSynonym
```

```http
POST /{databaseId}/synonyms/items/
Body (application/json):
{
  "term": "sofa",
  "synonym": "couch",
  "oneWay": false
}
```

---

Since version

3.2.0

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **3.2.0**

ID of your database.

---

term

String

Located in: **body**

Required: **Yes**

Since version: **3.2.0**

A word to which the `synonym` is specified.

---

synonym

String

Located in: **body**

Required: **Yes**

Since version: **3.2.0**

A word that should be considered equal to the `term` by the full-text search engine.

---

oneWay

Boolean

Located in: **body**

Required: **No**

Since version: **3.2.0**

If set to `true`, only `term` \-> `synonym` is considered. If set to `false`, also `synonym` \-> `term` works.

Default: `false`.

---

##### Responses

201

Successful operation. Returns data about the added synonym (including `id`).

```
{
  "id": "cc198c86-e015-bb74-b5f4-8f996fd26736",
  "term": "sci-fi",
  "synonym": "science fiction",
  "oneWay": false
}
```

---

400

Missing a field, or a field has a wrong type.

---

409

`synonym` and `term` pair already exists in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

get

#### List Search Synonyms

Gives the list of synonyms defined in the database.

```js
const result = await client.send(new requests.ListSearchSynonyms({
  // optional parameters:
  count: 10,  // integer
  offset: 0,  // integer
}));
```

```python
result = client.send(ListSearchSynonyms(
    # optional parameters:
    count=10,  # integer
    offset=0,  # integer
))
```

```ruby
result = client.send(ListSearchSynonyms.new({
  # optional parameters:
  count: 10,  # integer
  offset: 0,  # integer
}))
```

```java
ListSearchSynonymsResponse result = client.send(new ListSearchSynonyms()
    .setCount(10)  // long
    .setOffset(0)  // long
);
```

```php
$result = $client->send(new Reqs\ListSearchSynonyms([
    // optional parameters:
    'count' => 10,  // integer
    'offset' => 0,  // integer
]));
```

```csharp
ListSearchSynonymsResponse result = client.Send(new ListSearchSynonyms(
    // optional parameters:
    count: 10,  // long
    offset: 0   // long
));
```

```go
request := client.NewListSearchSynonyms().
    // optional parameters:
    SetCount(10).  // int
    SetOffset(0)   // int

result, err := request.Send() // result is of the type bindings.ListSearchSynonymsResponse
```

```http
GET /{databaseId}/synonyms/items/?count=10
&offset=0
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

count

Integer

Located in: **query**

Required: **No**

The number of synonyms to be listed.

---

offset

Integer

Located in: **query**

Required: **No**

Specifies the number of synonyms to skip (ordered by `term`).

---

##### Responses

200

Successful operation.

```
{
  "synonyms": [
    {
      "id": "cc198c86-e015-bb74-b5f4-8f996fd26736",
      "term": "sci-fi",
      "synonym": "science fiction",
      "oneWay": false
    },
    {
      "id": "33bef0e5-f6ee-ac04-8b80-7ba8ece1fe63",
      "term": "sitcom",
      "synonym": "situation comedy",
      "oneWay": false
    }
  ]
}
```

---

delete

#### Delete All Search Synonyms

Deletes all synonyms defined in the database.

```js
client.send(new requests.DeleteAllSearchSynonyms());
```

```python
client.send(DeleteAllSearchSynonyms())
```

```ruby
client.send(DeleteAllSearchSynonyms.new())
```

```java
client.send(new DeleteAllSearchSynonyms());
```

```php
$client->send(new Reqs\DeleteAllSearchSynonyms());
```

```csharp
client.Send(new DeleteAllSearchSynonyms());
```

```go
request := client.NewDeleteAllSearchSynonyms()

_, err := request.Send()
```

```http
DELETE /{databaseId}/synonyms/items/
```

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

##### Responses

200

Successful operation.

---

delete

#### Delete Search Synonym

Deletes synonym of the given `id`. This synonym is no longer taken into account in the [Search items](https://docs.recombee.com/api#search-items).

```js
client.send(new requests.DeleteSearchSynonym(id));
```

```python
client.send(DeleteSearchSynonym(id))
```

```ruby
client.send(DeleteSearchSynonym.new(id))
```

```java
client.send(new DeleteSearchSynonym(id));
```

```php
$client->send(new Reqs\DeleteSearchSynonym($id));
```

```csharp
client.Send(new DeleteSearchSynonym(id));
```

```go
request := client.NewDeleteSearchSynonym(id)

_, err := request.Send()
```

```http
DELETE /{databaseId}/synonyms/items/{id}
```

---

Calls Limit Per Minute

1000

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

id

String

Located in: **path**

Required: **Yes**

ID of the synonym that should be deleted.

---

##### Responses

200

Successful operation.

---

404

Synonym with the given `id` does not exist.

---

## Series

Items in the catalog may be organized into series, expressing an explicit, known ordering of items, if there is any. Typical examples of series may be consecutive TV show episodes, book titles, etc.

Each item may be added to zero or more series, and a series may also be added into another series, resulting in a "meta-series". This may be useful for modeling ordered seasons of a TV show that has the episodes in each season themselves ordered.

### Series definition

Methods for managing series - creating, listing, and deleting them.

put

#### Add Series

Creates a new series in the database.

```js
client.send(new requests.AddSeries(seriesId, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```python
client.send(AddSeries(series_id,
    # optional parameters:
    cascade_create=True,  # boolean
))
```

```ruby
client.send(AddSeries.new(series_id, {
  # optional parameters:
  cascade_create: true,  # boolean
}))
```

```java
client.send(new AddSeries(seriesId)
    .setCascadeCreate(true)  // boolean
);
```

```php
$client->send(new Reqs\AddSeries($series_id, [
    // optional parameters:
    'cascadeCreate' => true,  // boolean
]));
```

```csharp
client.Send(new AddSeries(seriesId,
    // optional parameters:
    cascadeCreate: true  // bool
));
```

```go
request := client.NewAddSeries(seriesId).
    // optional parameters:
    SetCascadeCreate(true)  // bool

_, err := request.Send()
```

```http
PUT /{databaseId}/series/{seriesId}
Body (application/json):
{
  "cascadeCreate": true
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

seriesId

String

Located in: **path**

Required: **Yes**

ID of the series to be created.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

If set to `true`, the item will be created with the same ID as the series. Default is `true`.

---

##### Responses

201

Successful operation.

---

400

The `seriesId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

409

Series of the given `seriesId` is already present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Delete Series

Deletes the series of the given `seriesId` from the database.

Deleting a series will only delete assignment of items to it, not the items themselves!

```js
client.send(new requests.DeleteSeries(seriesId, {
  // optional parameters:
  cascadeDelete: false,  // boolean
}));
```

```python
client.send(DeleteSeries(series_id,
    # optional parameters:
    cascade_delete=False,  # boolean
))
```

```ruby
client.send(DeleteSeries.new(series_id, {
  # optional parameters:
  cascade_delete: false,  # boolean
}))
```

```java
client.send(new DeleteSeries(seriesId)
    .setCascadeDelete(false)  // boolean
);
```

```php
$client->send(new Reqs\DeleteSeries($series_id, [
    // optional parameters:
    'cascadeDelete' => false,  // boolean
]));
```

```csharp
client.Send(new DeleteSeries(seriesId,
    // optional parameters:
    cascadeDelete: false  // bool
));
```

```go
request := client.NewDeleteSeries(seriesId).
    // optional parameters:
    SetCascadeDelete(false)  // bool

_, err := request.Send()
```

```http
DELETE /{databaseId}/series/{seriesId}
Body (application/json):
{
  "cascadeDelete": false
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

seriesId

String

Located in: **path**

Required: **Yes**

ID of the series to be deleted.

---

cascadeDelete

Boolean

Located in: **body**

Required: **No**

If set to `true`, item with the same ID as seriesId will be also deleted. Default is `false`.

---

##### Responses

200

Successful operation.

---

400

The `seriesId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Series of the given `seriesId` is not present in the database. In many cases, you may consider this code a success – it only tells you that nothing has been deleted from the database since the series was already not present. If there is no additional info in the JSON response, you probably have an error in your URL.

---

get

#### List Series

Gets the list of all the series currently present in the database.

```js
const result = await client.send(new requests.ListSeries());
```

```python
result = client.send(ListSeries())
```

```ruby
result = client.send(ListSeries.new())
```

```java
Series[] result = client.send(new ListSeries());
```

```php
$result = $client->send(new Reqs\ListSeries());
```

```csharp
IEnumerable<Series> result = client.Send(new ListSeries());
```

```go
request := client.NewListSeries()

result, err := request.Send() // result is of the type []bindings.Series
```

```http
GET /{databaseId}/series/list/
```

---

Calls Limit Per Minute

100

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

##### Responses

200

Successful operation.

```
[
  "series-1",
  "series-2",
  "series-3"
]
```

---

404

Invalid URL.

---

### Series items

Methods for adding items (or even series themselves) to series.

get

#### List Series Items

Lists all the items present in the given series, sorted according to their time index values.

```js
const result = await client.send(new requests.ListSeriesItems(seriesId));
```

```python
result = client.send(ListSeriesItems(series_id))
```

```ruby
result = client.send(ListSeriesItems.new(series_id))
```

```java
SeriesItem[] result = client.send(new ListSeriesItems(seriesId));
```

```php
$result = $client->send(new Reqs\ListSeriesItems($series_id));
```

```csharp
IEnumerable<SeriesItem> result = client.Send(new ListSeriesItems(seriesId));
```

```go
request := client.NewListSeriesItems(seriesId)

result, err := request.Send() // result is of the type []bindings.SeriesItem
```

```http
GET /{databaseId}/series/{seriesId}/items/
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

seriesId

String

Located in: **path**

Required: **Yes**

ID of the series whose items are to be listed.

---

##### Responses

200

Successful operation.

```
[
  {
    "itemType": "item",
    "itemId": "item-x",
    "time": 1
  },
  {
    "itemType": "item",
    "itemId": "item-y",
    "time": 2
  },
  {
    "itemType": "item",
    "itemId": "item-z",
    "time": 3
  }
]
```

---

400

The `seriesId` does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

404

Series of the given `seriesId` is not present in the database. If there is no additional info in the JSON response, you probably have an error in your URL.

---

post

#### Insert to Series

Inserts an existing item/series into a series of the given seriesId at a position determined by time.

```js
client.send(new requests.InsertToSeries(seriesId, itemType, itemId, time, {
  // optional parameters:
  cascadeCreate: true,  // boolean
}));
```

```python
client.send(InsertToSeries(series_id, item_type, item_id, time,
    # optional parameters:
    cascade_create=True,  # boolean
))
```

```ruby
client.send(InsertToSeries.new(series_id, item_type, item_id, time, {
  # optional parameters:
  cascade_create: true,  # boolean
}))
```

```java
client.send(new InsertToSeries(seriesId, itemType, itemId, time)
    .setCascadeCreate(true)  // boolean
);
```

```php
$client->send(new Reqs\InsertToSeries($series_id, $item_type, $item_id, $time, [
    // optional parameters:
    'cascadeCreate' => true,  // boolean
]));
```

```csharp
client.Send(new InsertToSeries(seriesId, itemType, itemId, time,
    // optional parameters:
    cascadeCreate: true  // bool
));
```

```go
request := client.NewInsertToSeries(seriesId, itemType, itemId, time).
    // optional parameters:
    SetCascadeCreate(true)  // bool

_, err := request.Send()
```

```http
POST /{databaseId}/series/{seriesId}/items/
Body (application/json):
{
  "itemType": "item",
  "itemId": "item-1",
  "time": 1,
  "cascadeCreate": true
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

seriesId

String

Located in: **path**

Required: **Yes**

ID of the series to be inserted into.

---

itemType

String

Located in: **body**

Required: **Yes**

`item` iff the regular item from the catalog is to be inserted, `series` iff series is inserted as the item.

---

itemId

String

Located in: **body**

Required: **Yes**

ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`.

---

time

Number

Located in: **body**

Required: **Yes**

Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time.

---

cascadeCreate

Boolean

Located in: **body**

Required: **No**

Indicates that any non-existing entity specified within the request should be created (as if corresponding PUT requests were invoked). This concerns both the `seriesId` and the `itemId`. If `cascadeCreate` is set to true, the behavior also depends on the `itemType`. In case of `item`, an item is created, in case of `series` a series + corresponding item with the same ID is created.

---

##### Responses

200

Successful operation.

---

400

`seriesId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$, or `itemType`∉{item,series}, or `time` is not a real number.

---

404

Series of the given `seriesId` is not present in the database. Item of the given `itemId` is not present in the database if `itemType` is item. Series of the given `itemId` is not present in the database if `itemType` is series. If there is no additional info in the JSON response, you probably have an error in your URL.

---

409

A series item of the exact same (`itemType`, `itemId`, `time`) is already present in the series of `seriesId`. In many cases, you may consider this code a success – it only tells you that nothing has been written to the database.

---

delete

#### Remove from Series

Removes an existing series item from the series.

```js
client.send(new requests.RemoveFromSeries(seriesId, itemType, itemId));
```

```python
client.send(RemoveFromSeries(series_id, item_type, item_id))
```

```ruby
client.send(RemoveFromSeries.new(series_id, item_type, item_id))
```

```java
client.send(new RemoveFromSeries(seriesId, itemType, itemId));
```

```php
$client->send(new Reqs\RemoveFromSeries($series_id, $item_type, $item_id));
```

```csharp
client.Send(new RemoveFromSeries(seriesId, itemType, itemId));
```

```go
request := client.NewRemoveFromSeries(seriesId, itemType, itemId)

_, err := request.Send()
```

```http
DELETE /{databaseId}/series/{seriesId}/items/
Body (application/json):
{
  "itemType": "item",
  "itemId": "item-1"
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

seriesId

String

Located in: **path**

Required: **Yes**

ID of the series from which a series item is to be removed.

---

itemType

String

Located in: **body**

Required: **Yes**

Type of the item to be removed.

---

itemId

String

Located in: **body**

Required: **Yes**

ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`.

---

##### Responses

200

Successful operation.

---

400

The `seriesId` or `itemId` does not match ^\[a-zA-Z0-9\_-:@.\]+$ or `itemType`∉{`item`, `series`}.

---

404

Series of the given `seriesId` is not present in the database. Series item given by pair (`itemType`, `itemId`) is not present in series of `seriesId`. If there is no additional info in the JSON response, you probably have an error in your URL.

---

## Segmentations Definition

Segmentations allow you to group the Items into various segments: For example segment articles or products by categories, segment movies by genres, etc. The Segmentations can be used in recommendations (e.g. return the most relevant categories for a user).

See [this section](https://docs.recombee.com/segmentations) for more info.

### Property Based Segmentation

Property-based Segmentation groups the Items by the value of a particular property. See [this section](https://docs.recombee.com/segmentations#property-based-segmentation) for more info.

put

#### Create Property Based Segmentation

Creates a Segmentation that splits the items into segments based on values of a particular item property.

A segment is created for each unique value of the property. In case of `set` properties, a segment is created for each value in the set. Item belongs to all these segments.

```js
client.send(new requests.CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName, {
  // optional parameters:
  title: 'Categories',                                    // string
  description: 'Segmentation based on item categories.',  // string
}));
```

```python
client.send(CreatePropertyBasedSegmentation(segmentation_id, source_type, property_name,
    # optional parameters:
    title='Categories',                                    # string
    description='Segmentation based on item categories.',  # string
))
```

```ruby
client.send(CreatePropertyBasedSegmentation.new(segmentation_id, source_type, property_name, {
  # optional parameters:
  title: 'Categories',                                    # string
  description: 'Segmentation based on item categories.',  # string
}))
```

```java
client.send(new CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName)
    .setTitle("Categories")                                    // String
    .setDescription("Segmentation based on item categories.")  // String
);
```

```php
$client->send(new Reqs\CreatePropertyBasedSegmentation($segmentation_id, $source_type, $property_name, [
    // optional parameters:
    'title' => 'Categories',                                    // string
    'description' => 'Segmentation based on item categories.',  // string
]));
```

```csharp
client.Send(new CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName,
    // optional parameters:
    title: "Categories",                                   // string
    description: "Segmentation based on item categories."  // string
));
```

```go
request := client.NewCreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName).
    // optional parameters:
    SetTitle("Categories").                                   // string
    SetDescription("Segmentation based on item categories.")  // string

_, err := request.Send()
```

```http
PUT /{databaseId}/segmentations/property-based/{segmentationId}
Body (application/json):
{
  "sourceType": "items",
  "propertyName": "categories",
  "title": "Categories",
  "description": "Segmentation based on item categories."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the newly created Segmentation

---

sourceType

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

What type of data should be segmented. Currently only `items` are supported.

---

propertyName

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

Name of the property on which the Segmentation should be based

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, property is not of supported type (`string` or `set`).

---

404

Property does not exist.

---

post

#### Update Property Based Segmentation

Updates a Property Based Segmentation

```js
client.send(new requests.UpdatePropertyBasedSegmentation(segmentationId, {
  // optional parameters:
  propertyName: 'categories',                             // string
  title: 'Categories',                                    // string
  description: 'Segmentation based on item categories.',  // string
}));
```

```python
client.send(UpdatePropertyBasedSegmentation(segmentation_id,
    # optional parameters:
    property_name='categories',                            # string
    title='Categories',                                    # string
    description='Segmentation based on item categories.',  # string
))
```

```ruby
client.send(UpdatePropertyBasedSegmentation.new(segmentation_id, {
  # optional parameters:
  property_name: 'categories',                            # string
  title: 'Categories',                                    # string
  description: 'Segmentation based on item categories.',  # string
}))
```

```java
client.send(new UpdatePropertyBasedSegmentation(segmentationId)
    .setPropertyName("categories")                             // String
    .setTitle("Categories")                                    // String
    .setDescription("Segmentation based on item categories.")  // String
);
```

```php
$client->send(new Reqs\UpdatePropertyBasedSegmentation($segmentation_id, [
    // optional parameters:
    'propertyName' => 'categories',                             // string
    'title' => 'Categories',                                    // string
    'description' => 'Segmentation based on item categories.',  // string
]));
```

```csharp
client.Send(new UpdatePropertyBasedSegmentation(segmentationId,
    // optional parameters:
    propertyName: "categories",                            // string
    title: "Categories",                                   // string
    description: "Segmentation based on item categories."  // string
));
```

```go
request := client.NewUpdatePropertyBasedSegmentation(segmentationId).
    // optional parameters:
    SetPropertyName("categories").                            // string
    SetTitle("Categories").                                   // string
    SetDescription("Segmentation based on item categories.")  // string

_, err := request.Send()
```

```http
POST /{databaseId}/segmentations/property-based/{segmentationId}
Body (application/json):
{
  "propertyName": "categories",
  "title": "Categories",
  "description": "Segmentation based on item categories."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the updated Segmentation

---

propertyName

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Name of the property on which the Segmentation should be based

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, property is not of supported type (`string` or `set`).

---

404

Property does not exist. Segmentation with given ID does not exist.

---

### Manual ReQL Segmentation

Segmentation whose Segments are defined by ReQL filters. See [this section](https://docs.recombee.com/segmentations#manual-reql-segmentation) for more info.

put

#### Create Manual ReQL Segmentation

Segment the items using multiple [ReQL](https://docs.recombee.com/reql) filters.

Use the Add Manual ReQL Items Segment endpoint to create the individual segments.

```js
client.send(new requests.CreateManualReqlSegmentation(segmentationId, sourceType, {
  // optional parameters:
  title: 'Homepage Rows',                                                       // string
  description: 'Segmentation grouping items into rows shown on the homepage.',  // string
}));
```

```python
client.send(CreateManualReqlSegmentation(segmentation_id, source_type,
    # optional parameters:
    title='Homepage Rows',                                                       # string
    description='Segmentation grouping items into rows shown on the homepage.',  # string
))
```

```ruby
client.send(CreateManualReqlSegmentation.new(segmentation_id, source_type, {
  # optional parameters:
  title: 'Homepage Rows',                                                       # string
  description: 'Segmentation grouping items into rows shown on the homepage.',  # string
}))
```

```java
client.send(new CreateManualReqlSegmentation(segmentationId, sourceType)
    .setTitle("Homepage Rows")                                                       // String
    .setDescription("Segmentation grouping items into rows shown on the homepage.")  // String
);
```

```php
$client->send(new Reqs\CreateManualReqlSegmentation($segmentation_id, $source_type, [
    // optional parameters:
    'title' => 'Homepage Rows',                                                       // string
    'description' => 'Segmentation grouping items into rows shown on the homepage.',  // string
]));
```

```csharp
client.Send(new CreateManualReqlSegmentation(segmentationId, sourceType,
    // optional parameters:
    title: "Homepage Rows",                                                      // string
    description: "Segmentation grouping items into rows shown on the homepage."  // string
));
```

```go
request := client.NewCreateManualReqlSegmentation(segmentationId, sourceType).
    // optional parameters:
    SetTitle("Homepage Rows").                                                      // string
    SetDescription("Segmentation grouping items into rows shown on the homepage.")  // string

_, err := request.Send()
```

```http
PUT /{databaseId}/segmentations/manual-reql/{segmentationId}
Body (application/json):
{
  "sourceType": "items",
  "title": "Homepage Rows",
  "description": "Segmentation grouping items into rows shown on the homepage."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the newly created Segmentation

---

sourceType

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

What type of data should be segmented. Currently only `items` are supported.

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$.

---

##### Examples

###### Example Create a Manual ReQL Segmentation and set up its Segments

Each Segment is defined by a ReQL filter: Items passing the filter belong to the Segment.

Here we create two Segments in the `homepage-rows` Segmentation:

* `made-in-us` contains items that were created in the US
* `short-laughs` contains comedies with runtime under 30 minutes

See [this section](https://docs.recombee.com/segmentations#manual-reql-based-segmentation) for more info.

```python
reqs = [
  CreateManualReqlSegmentation("homepage-rows", "items"),
  AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "),
  AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30")
]

responses = client.send(Batch(reqs))
```

```ruby
batch = Batch.new([
    CreateManualReqlSegmentation.new('homepage-rows', 'items'),
    AddManualReqlSegment.new('homepage-rows', 'made-in-us', "'country' == \"US\" "),
    AddManualReqlSegment.new('homepage-rows', 'short-laughs', "\"Comedy\" in 'genres' and 'runtime' < 30")
])

response = client.send(batch)
```

```java
Request[] requests = new Request[] {
    new CreateManualReqlSegmentation("homepage-rows", "items"),
    new AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "),
    new AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30")
};

BatchResponse[] responses = client.send(new Batch(requests));
```

```js
const batch = new Batch([
    new CreateManualReqlSegmentation('homepage-rows', 'items'),
    new AddManualReqlSegment('homepage-rows', 'made-in-us', "'country' == \"US\" "),
    new AddManualReqlSegment('homepage-rows', 'short-laughs', "\"Comedy\" in 'genres' and 'runtime' < 30")
]);

const responses = await client.send(batch);
```

```php
$reqs = [
    new Reqs\CreateManualReqlSegmentation("homepage-rows", "items"),
    new Reqs\AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "),
    new Reqs\AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30")
];

$responses = $client->send(new Reqs\Batch($reqs));
```

```csharp
Request[] requests = new Request[] {
    new CreateManualReqlSegmentation("homepage-rows", "items"),
    new AddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\" "),
    new AddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30")
};

BatchResponse batchResponse = await client.SendAsync(new Batch(requests));
```

```go
import (
  "github.com/recombee/go-api-client/v6/recombee"
  "github.com/recombee/go-api-client/v6/recombee/requests"
)

reqs := []requests.Request{
  // Assuming methods similar to the Java SDK exist in the Go SDK
  client.NewCreateManualReqlSegmentation("homepage-rows", "items"),
  client.NewAddManualReqlSegment("homepage-rows", "made-in-us", "'country' == \"US\""),
  client.NewAddManualReqlSegment("homepage-rows", "short-laughs", "\"Comedy\" in 'genres' and 'runtime' < 30"),
}

// Send the batch request
batchRes, err := client.NewBatch(reqs).Send()
```

post

#### Update Manual ReQL Segmentation

Update an existing Segmentation.

```js
client.send(new requests.UpdateManualReqlSegmentation(segmentationId, {
  // optional parameters:
  title: 'Homepage Rows',                                                       // string
  description: 'Segmentation grouping items into rows shown on the homepage.',  // string
}));
```

```python
client.send(UpdateManualReqlSegmentation(segmentation_id,
    # optional parameters:
    title='Homepage Rows',                                                       # string
    description='Segmentation grouping items into rows shown on the homepage.',  # string
))
```

```ruby
client.send(UpdateManualReqlSegmentation.new(segmentation_id, {
  # optional parameters:
  title: 'Homepage Rows',                                                       # string
  description: 'Segmentation grouping items into rows shown on the homepage.',  # string
}))
```

```java
client.send(new UpdateManualReqlSegmentation(segmentationId)
    .setTitle("Homepage Rows")                                                       // String
    .setDescription("Segmentation grouping items into rows shown on the homepage.")  // String
);
```

```php
$client->send(new Reqs\UpdateManualReqlSegmentation($segmentation_id, [
    // optional parameters:
    'title' => 'Homepage Rows',                                                       // string
    'description' => 'Segmentation grouping items into rows shown on the homepage.',  // string
]));
```

```csharp
client.Send(new UpdateManualReqlSegmentation(segmentationId,
    // optional parameters:
    title: "Homepage Rows",                                                      // string
    description: "Segmentation grouping items into rows shown on the homepage."  // string
));
```

```go
request := client.NewUpdateManualReqlSegmentation(segmentationId).
    // optional parameters:
    SetTitle("Homepage Rows").                                                      // string
    SetDescription("Segmentation grouping items into rows shown on the homepage.")  // string

_, err := request.Send()
```

```http
POST /{databaseId}/segmentations/manual-reql/{segmentationId}
Body (application/json):
{
  "title": "Homepage Rows",
  "description": "Segmentation grouping items into rows shown on the homepage."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the updated Segmentation

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Given Segmentation is of different type.

---

404

Segmentation with given ID does not exist.

---

put

#### Add Manual ReQL Segment

Adds a new Segment into a Manual ReQL Segmentation.

The new Segment is defined by a [ReQL](https://docs.recombee.com/reql) filter that returns `true` for an item in case that this item belongs to the segment.

```js
client.send(new requests.AddManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  title: 'Newly published',  // string
}));
```

```python
client.send(AddManualReqlSegment(segmentation_id, segment_id, filter,
    # optional parameters:
    title='Newly published',  # string
))
```

```ruby
client.send(AddManualReqlSegment.new(segmentation_id, segment_id, filter, {
  # optional parameters:
  title: 'Newly published',  # string
}))
```

```java
client.send(new AddManualReqlSegment(segmentationId, segmentId, filter)
    .setTitle("Newly published")  // String
);
```

```php
$client->send(new Reqs\AddManualReqlSegment($segmentation_id, $segment_id, $filter, [
    // optional parameters:
    'title' => 'Newly published',  // string
]));
```

```csharp
client.Send(new AddManualReqlSegment(segmentationId, segmentId, filter,
    // optional parameters:
    title: "Newly published"  // string
));
```

```go
request := client.NewAddManualReqlSegment(segmentationId, segmentId, filter).
    // optional parameters:
    SetTitle("Newly published")  // string

_, err := request.Send()
```

```http
PUT /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}
Body (application/json):
{
  "filter": "true",
  "title": "Newly published"
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segmentation to which the new Segment should be added

---

segmentId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the newly created Segment

---

filter

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

ReQL filter that returns `true` for items that belong to this Segment. Otherwise returns `false`.

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name of the Segment that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type.

---

404

Segmentation with given ID does not exist.

---

post

#### Update Manual ReQL Segment

Update definition of the Segment.

```js
client.send(new requests.UpdateManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  title: 'Newly published',  // string
}));
```

```python
client.send(UpdateManualReqlSegment(segmentation_id, segment_id, filter,
    # optional parameters:
    title='Newly published',  # string
))
```

```ruby
client.send(UpdateManualReqlSegment.new(segmentation_id, segment_id, filter, {
  # optional parameters:
  title: 'Newly published',  # string
}))
```

```java
client.send(new UpdateManualReqlSegment(segmentationId, segmentId, filter)
    .setTitle("Newly published")  // String
);
```

```php
$client->send(new Reqs\UpdateManualReqlSegment($segmentation_id, $segment_id, $filter, [
    // optional parameters:
    'title' => 'Newly published',  // string
]));
```

```csharp
client.Send(new UpdateManualReqlSegment(segmentationId, segmentId, filter,
    // optional parameters:
    title: "Newly published"  // string
));
```

```go
request := client.NewUpdateManualReqlSegment(segmentationId, segmentId, filter).
    // optional parameters:
    SetTitle("Newly published")  // string

_, err := request.Send()
```

```http
POST /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}
Body (application/json):
{
  "filter": "true",
  "title": "Newly published"
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segmentation to which the updated Segment belongs

---

segmentId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segment that will be updated

---

filter

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

ReQL filter that returns `true` for items that belong to this Segment. Otherwise returns `false`.

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name of the Segment that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type.

---

404

Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.

---

delete

#### Delete Manual ReQL Segment

Delete a Segment from a Manual ReQL Segmentation.

```js
client.send(new requests.DeleteManualReqlSegment(segmentationId, segmentId));
```

```python
client.send(DeleteManualReqlSegment(segmentation_id, segment_id))
```

```ruby
client.send(DeleteManualReqlSegment.new(segmentation_id, segment_id))
```

```java
client.send(new DeleteManualReqlSegment(segmentationId, segmentId));
```

```php
$client->send(new Reqs\DeleteManualReqlSegment($segmentation_id, $segment_id));
```

```csharp
client.Send(new DeleteManualReqlSegment(segmentationId, segmentId));
```

```go
request := client.NewDeleteManualReqlSegment(segmentationId, segmentId)

_, err := request.Send()
```

```http
DELETE /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segmentation from which the Segment should be deleted

---

segmentId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segment that should be deleted

---

##### Responses

201

successful operation

---

400

segmentationId or segmentId does not match ^\[a-zA-Z0-9\_-:@.\]+$. Segmentation is of wrong type.

---

404

Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.

---

### Auto ReQL Segmentation

Auto ReQL Segmentation is specified by a ReQL expression that for each Item returns a set of Segments to which the Item belongs. See [this section](https://docs.recombee.com/segmentations#auto-reql-segmentation) for more info.

put

#### Create Auto ReQL Segmentation

Segment the items using a [ReQL](https://docs.recombee.com/reql) expression.

For each item, the expression should return a set that contains IDs of segments to which the item belongs to.

```js
client.send(new requests.CreateAutoReqlSegmentation(segmentationId, sourceType, expression, {
  // optional parameters:
  title: 'Country and Genre',                                               // string
  description: 'Segmentation combining item genre and country of origin.',  // string
}));
```

```python
client.send(CreateAutoReqlSegmentation(segmentation_id, source_type, expression,
    # optional parameters:
    title='Country and Genre',                                               # string
    description='Segmentation combining item genre and country of origin.',  # string
))
```

```ruby
client.send(CreateAutoReqlSegmentation.new(segmentation_id, source_type, expression, {
  # optional parameters:
  title: 'Country and Genre',                                               # string
  description: 'Segmentation combining item genre and country of origin.',  # string
}))
```

```java
client.send(new CreateAutoReqlSegmentation(segmentationId, sourceType, expression)
    .setTitle("Country and Genre")                                               // String
    .setDescription("Segmentation combining item genre and country of origin.")  // String
);
```

```php
$client->send(new Reqs\CreateAutoReqlSegmentation($segmentation_id, $source_type, $expression, [
    // optional parameters:
    'title' => 'Country and Genre',                                               // string
    'description' => 'Segmentation combining item genre and country of origin.',  // string
]));
```

```csharp
client.Send(new CreateAutoReqlSegmentation(segmentationId, sourceType, expression,
    // optional parameters:
    title: "Country and Genre",                                              // string
    description: "Segmentation combining item genre and country of origin."  // string
));
```

```go
request := client.NewCreateAutoReqlSegmentation(segmentationId, sourceType, expression).
    // optional parameters:
    SetTitle("Country and Genre").                                              // string
    SetDescription("Segmentation combining item genre and country of origin.")  // string

_, err := request.Send()
```

```http
PUT /{databaseId}/segmentations/auto-reql/{segmentationId}
Body (application/json):
{
  "sourceType": "items",
  "expression": "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
  "title": "Country and Genre",
  "description": "Segmentation combining item genre and country of origin."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the newly created Segmentation

---

sourceType

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

What type of data should be segmented. Currently only `items` are supported.

---

expression

String

Located in: **body**

Required: **Yes**

Since version: **4.1.0**

ReQL expression that returns for each item a set with IDs of segments to which the item belongs

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$, ReQL expression is invalid.

---

##### Examples

###### Example Create an Auto ReQL Segmentation

Create a Segmentation, whose Segments combine the country of origin and the genre.

See [this section](https://docs.recombee.com/segmentations#auto-reql-based-segmentation) for more info.

```python
req = CreateAutoReqlSegmentation(
    "country-and-genre",
    "items",
    "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
)

response = client.send(req)
```

```ruby
req = CreateAutoReqlSegmentation.new(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
)

response = client.send(req)
```

```java
CreateAutoReqlSegmentation req = new CreateAutoReqlSegmentation(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
);

client.send(req);
```

```js
const req = new CreateAutoReqlSegmentation(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
);

const response = await client.send(req);
```

```php
$req = new Reqs\CreateAutoReqlSegmentation(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
);

$response = $client->send($req);
```

```csharp
var req = new CreateAutoReqlSegmentation(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
);

client.Send(req);
```

```go
req := client.NewCreateAutoReqlSegmentation(
  "country-and-genre",
  "items",
  "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
)

_, err = req.Send()
```

post

#### Update Auto ReQL Segmentation

Update an existing Segmentation.

```js
client.send(new requests.UpdateAutoReqlSegmentation(segmentationId, {
  // optional parameters:
  expression: 'map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')',  // string
  title: 'Country and Genre',                                                      // string
  description: 'Segmentation combining item genre and country of origin.',         // string
}));
```

```python
client.send(UpdateAutoReqlSegmentation(segmentation_id,
    # optional parameters:
    expression='map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')',  # string
    title='Country and Genre',                                                      # string
    description='Segmentation combining item genre and country of origin.',         # string
))
```

```ruby
client.send(UpdateAutoReqlSegmentation.new(segmentation_id, {
  # optional parameters:
  expression: 'map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')',  # string
  title: 'Country and Genre',                                                      # string
  description: 'Segmentation combining item genre and country of origin.',         # string
}))
```

```java
client.send(new UpdateAutoReqlSegmentation(segmentationId)
    .setExpression("map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')")  // String
    .setTitle("Country and Genre")                                                // String
    .setDescription("Segmentation combining item genre and country of origin.")   // String
);
```

```php
$client->send(new Reqs\UpdateAutoReqlSegmentation($segmentation_id, [
    // optional parameters:
    'expression' => 'map(lambda \'genre\': \'genre\' + "-" + \'country\', \'genres\')',  // string
    'title' => 'Country and Genre',                                                      // string
    'description' => 'Segmentation combining item genre and country of origin.',         // string
]));
```

```csharp
client.Send(new UpdateAutoReqlSegmentation(segmentationId,
    // optional parameters:
    expression: "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",  // string
    title: "Country and Genre",                                                // string
    description: "Segmentation combining item genre and country of origin."    // string
));
```

```go
request := client.NewUpdateAutoReqlSegmentation(segmentationId).
    // optional parameters:
    SetExpression("map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')").  // string
    SetTitle("Country and Genre").                                                // string
    SetDescription("Segmentation combining item genre and country of origin.")    // string

_, err := request.Send()
```

```http
POST /{databaseId}/segmentations/auto-reql/{segmentationId}
Body (application/json):
{
  "expression": "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
  "title": "Country and Genre",
  "description": "Segmentation combining item genre and country of origin."
}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the updated Segmentation

---

expression

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

ReQL expression that returns for each item a set with IDs of segments to which the item belongs

---

title

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Human-readable name that is shown in the Recombee Admin UI.

---

description

String

Located in: **body**

Required: **No**

Since version: **4.1.0**

Description that is shown in the Recombee Admin UI.

---

##### Responses

201

successful operation

---

400

segmentationId does not match ^\[a-zA-Z0-9\_-:@.\]+$. ReQL expression is invalid. Given Segmentation is of different type.

---

404

Segmentation with given ID does not exist.

---

### General

get

#### List Segmentations

Return all existing items Segmentations.

```js
const result = await client.send(new requests.ListSegmentations(sourceType));
```

```python
result = client.send(ListSegmentations(source_type))
```

```ruby
result = client.send(ListSegmentations.new(source_type))
```

```java
ListSegmentationsResponse result = client.send(new ListSegmentations(sourceType));
```

```php
$result = $client->send(new Reqs\ListSegmentations($source_type));
```

```csharp
ListSegmentationsResponse result = client.Send(new ListSegmentations(sourceType));
```

```go
request := client.NewListSegmentations(sourceType)

result, err := request.Send() // result is of the type bindings.ListSegmentationsResponse
```

```http
GET /{databaseId}/segmentations/list/?sourceType=items
```

---

Since version

4.1.0

---

Calls Limit Per Minute

60

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

sourceType

String

Located in: **query**

Required: **Yes**

Since version: **4.1.0**

List Segmentations based on a particular type of data. Currently only `items` are supported.

---

##### Responses

200

```
{
  "segmentations": [
    {
      "segmentationId": "category",
      "sourceType": "items",
      "segmentationType": "property",
      "title": "Category Segmentation",
      "description": "Groups items by their category"
    },
    {
      "segmentationId": "homepage-rows",
      "sourceType": "items",
      "segmentationType": "manualReQL",
      "title": "Homepage Rows",
      "description": "Defines individual content rows that can be shown on the homepage"
    }
  ]
}
```

---

get

#### Get Segmentation

Get existing Segmentation.

```js
const result = await client.send(new requests.GetSegmentation(segmentationId));
```

```python
result = client.send(GetSegmentation(segmentation_id))
```

```ruby
result = client.send(GetSegmentation.new(segmentation_id))
```

```java
Segmentation result = client.send(new GetSegmentation(segmentationId));
```

```php
$result = $client->send(new Reqs\GetSegmentation($segmentation_id));
```

```csharp
Segmentation result = client.Send(new GetSegmentation(segmentationId));
```

```go
request := client.NewGetSegmentation(segmentationId)

result, err := request.Send() // result is of the type bindings.Segmentation
```

```http
GET /{databaseId}/segmentations/list/{segmentationId}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segmentation that should be returned

---

##### Responses

200

```
{
  "segmentationId": "category",
  "sourceType": "items",
  "segmentationType": "property",
  "title": "Category Segmentation",
  "description": "Groups items by their category"
}
```

---

404

Segmentation with given ID does not exist.

---

delete

#### Delete Segmentation

Delete existing Segmentation.

```js
client.send(new requests.DeleteSegmentation(segmentationId));
```

```python
client.send(DeleteSegmentation(segmentation_id))
```

```ruby
client.send(DeleteSegmentation.new(segmentation_id))
```

```java
client.send(new DeleteSegmentation(segmentationId));
```

```php
$client->send(new Reqs\DeleteSegmentation($segmentation_id));
```

```csharp
client.Send(new DeleteSegmentation(segmentationId));
```

```go
request := client.NewDeleteSegmentation(segmentationId)

_, err := request.Send()
```

```http
DELETE /{databaseId}/segmentations/{segmentationId}
```

---

Since version

4.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of your database.

---

segmentationId

String

Located in: **path**

Required: **Yes**

Since version: **4.1.0**

ID of the Segmentation that should be deleted

---

##### Responses

200

successful operation

---

404

Segmentation with given ID does not exist.

---

## Miscellaneous

post

#### Batch

Allowed on Client-Side

Batch processing allows you to submit arbitrary sequence of requests within a single HTTPS request.

Any type of request from the above documentation may be used in the Batch, and the Batch may combine different types of requests arbitrarily as well.

Using Batch requests is beneficial for example, when synchronizing the catalog of items or uploading historical interaction data, as sending the data in Batch is considerably faster than sending the individual requests (thanks to optimizations and reducing network and HTTPS overhead).

```js
const result = await client.send(new recombee.Batch(requests, {
  // optional parameters:
  distinctRecomms: true,  // boolean
}));
```

```kotlin
val result = client.sendAsync(Batch(requests,
    // optional parameters:
    distinctRecomms = true,  // Boolean
))

result.onSuccess { response: List<BatchResponse> ->
    // Handle response
}.onFailure { exception -> // ApiException
    // Handle exception
}
```

```swift
let result: [BatchResponse<AnyRecombeeBinding>] = try await client.send(Batch(requests: requests,
    // optional parameters:
    distinctRecomms: true  // Bool
))
```

```js
const result = await client.send(new requests.Batch(reqs, {
  // optional parameters:
  distinctRecomms: true,  // boolean
}));
```

```python
result = client.send(Batch(requests,
    # optional parameters:
    distinct_recomms=True,  # boolean
))
```

```ruby
result = client.send(Batch.new(requests, {
  # optional parameters:
  distinct_recomms: true,  # boolean
}))
```

```java
BatchResponse[] result = client.send(new Batch(requests)
    .setDistinctRecomms(true)  // boolean
);
```

```php
$result = $client->send(new Reqs\Batch($requests, [
    // optional parameters:
    'distinctRecomms' => true,  // boolean
]));
```

```csharp
BatchResponse result = client.Send(new Batch(requests,
    // optional parameters:
    distinctRecomms: true  // bool
));
```

```go
request := client.NewBatch(reqs).
    // optional parameters:
    SetDistinctRecomms(true)  // bool

result, err := request.Send() // result is of the type []bindings.BatchResponse
```

```http
POST /{databaseId}/batch/
Body (application/json):
{
  "requests": [],
  "distinctRecomms": true
}
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

requests

Array

Located in: **body**

Required: **Yes**

JSON array containing the requests.

---

distinctRecomms

Boolean

Located in: **body**

Required: **No**

Since version: **1.2.4**

Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch.

---

##### Responses

200

Successful operation. There is an array with responses. The order of the responses in the array follows the order of the sent requests.

```
[
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": "ok"
  },
  {
    "code": 200,
    "json": {
      "recommId": "3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb",
      "recomms": [
        {
          "id": "item-146"
        },
        {
          "id": "item-462"
        },
        {
          "id": "item-463"
        }
      ],
      "numberNextRecommsCalls": 0
    }
  }
]
```

---

400

Many possibilities, see the error description in the result JSON. Examples: invalid or missing Content-type (not `application/json`), request body is not a valid JSON, request JSON does not have the prescribed structure.

---

404

There is at least one request in the batch with an invalid (non-existing) URL. In such a case, the batch as a whole **is not executed** and you'll get HTTP 404, because the batch is apriori erroneous.

---

413

Too large batch (containing more than 10,000 requests in case of a server side request).

---

##### Examples

###### Example Sending multiple requests in a single Batch request

Batch can encapsulate requests of various types.

```js
let reqs = [new recombee.AddDetailView(userId, itemId),
            new recombee.RecommendItemsToUser(userId, 5, {scenario: 'just_for_you'}),
            new recombee.RecommendItemsToItem(itemId, userId, 5, {scenario: 'similar_products'})
           ];

const responses = await client.send(new recombee.Batch(reqs));
```

```kotlin
val requests = listOf(
    AddDetailView(
        userId = "userId",
        itemId = "itemId",
        cascadeCreate = true
    ),

    RecommendItemsToUser(
        userId = "userId",
        count = 5,
        scenario = "just_for_you",
        cascadeCreate = true
    ),

    RecommendItemsToItem(
        itemId = "itemId",
        targetUserId = "userId",
        count = 5,
        scenario = "similar_products",
        cascadeCreate = true
    ),
)

val responses = client.send(Batch(requests))
```

```swift
let requests: [any Request] = [
    AddDetailView(
        userId: "userId",
        itemId: "itemId",
        cascadeCreate: true
    ),
    RecommendItemsToUser(
        userId: "userId",
        count: 5,
        scenario: "just_for_you",
        cascadeCreate: true
    ),
    RecommendItemsToItem(
        itemId: "itemId",
        targetUserId: "userId",
        count: 5,
        scenario: "similar_products",
        cascadeCreate: true
    )
]

let batchRequest = Batch(requests: requests)
let responses = try await client.send(batchRequest)
```

```python
reqs = [AddDetailView(user_id, item_id, cascade_create=True),
        RecommendItemsToUser(user_id, 5, scenario="just_for_you", cascade_create=True),
        RecommendItemsToItem(item_id, user_id, 5, scenario="similar_products", cascade_create=True),
        SetItemValues(item_id, {"price": 200, "category": "furniture"}, cascade_create=True)
       ]
responses = client.send(Batch(reqs))
```

```ruby
requests = [AddDetailView.new(user_id, item_id, {:cascade_create => true}),
            RecommendItemsToUser.new(user_id, 5, {:scenario => 'just_for_you', :cascade_create => true}),
            RecommendItemsToItem.new(item_id, user_id, 5, {:scenario => 'similar_products', :cascade_create => true}),
            SetItemValues(item_id, {"price" => 200, "category" => "furniture"}, {:cascade_create => true})
           ]
responses = client.send(Batch.new(requests))
```

```java
Request[] requests = new Request[] {
  new AddDetailView(userId, itemId).setCascadeCreate(true),
  new RecommendItemsToUser(userId, 5).setScenario("just_for_you").setCascadeCreate(true),
  new RecommendItemsToItem(itemId, userId, 5).setScenario("similar_products").setCascadeCreate(true),
  new SetItemValues(itemId, new HashMap<String, Object>(){{put("price", 200); put("category", "furniture");}})
};

BatchResponse[] responses = client.send(new Batch(requests));
```

```js
let reqs = [new rqs.AddDetailView(userId, itemId, {cascadeCreate: true}),
            new rqs.RecommendItemsToUser(userId, 5, {scenario: 'just_for_you', cascadeCreate: true}),
            new rqs.RecommendItemsToItem(itemId, userId, 5, {scenario: 'similar_products', cascadeCreate: true}),
            new rqs.SetItemValues(itemId, {price: 200, category: 'furniture'}, {cascadeCreate: true})
           ];

const responses = await client.send(new rqs.Batch(reqs));
```

```php
$reqs = [
            new Reqs\AddDetailView(userId, itemId, ['cascadeCreate' => true]),
            new Reqs\RecommendItemsToUser(userId, 5, ['scenario' => 'just_for_you', 'cascadeCreate' => true]),
            new Reqs\RecommendItemsToItem(userId, itemId, 5, ['scenario' => 'similar_products', 'cascadeCreate' => true]),
            new Reqs\SetItemValues(itemId, ['price' => 200, 'category' => 'furniture'], ['cascadeCreate' => true]),
        ];
$replies = $client->send(new Reqs\Batch($reqs));
```

```csharp
Request[] requests = new Request[] {
    new AddDetailView(userId, itemId, cascadeCreate: true),
    new RecommendItemsToUser(userId, 5, scenario: "just_for_you", cascadeCreate: true),
    new RecommendItemsToItem(itemId, userId, 5, scenario: "similar_products", cascadeCreate: true),
    new SetItemValues(itemId, new Dictionary<string, object>(){{"price", 200}, {"category", "furniture"}})
};

BatchResponse batchResponse = await client.SendAsync(new Batch(requests));
```

```go
import (
  "github.com/recombee/go-api-client/v6/recombee"
  "github.com/recombee/go-api-client/v6/recombee/requests"
)

requestsBatch := []requests.Request{
  client.NewAddDetailView(userId, itemId).SetCascadeCreate(true),
  client.NewRecommendItemsToUser(userId, 5).SetScenario("just_for_you").SetCascadeCreate(true),
  client.NewRecommendItemsToItem(itemId, userId, 5).SetScenario("similar_products").SetCascadeCreate(true),
  client.NewSetItemValues(itemId, map[string]interface{}{
    "price":    200,
    "category": "furniture",
  }).SetCascadeCreate(true),
}

// Send batch request
batchRes, err := client.NewBatch(requestsBatch).Send()
```

```http
# If you use the REST API directly, than the body of a batch request consists of a JSON object. 
# The individual requests are given as a JSON array associated with key *requests*. 
#
# In the array, each request is encoded as a JSON object containing the following fields:
#
# * method – required string with HTTP method of the request (one of PUT, POST, GET, DELETE, case insensitive),
# * path – required string with path of the request from the root of the database, excluding the query string,
# * params – optional (or required if also required by the request type) object containing values 
#            of the request's parameters (GET or POST, depending on the request type)
#
# The `params` property may be omitted if there are no attributes to be passed for the request;
# if some attributes are optional, you may or may not include them as in regular request,
#
# Example of executing three requests (setting the item values, adding a detail view,
#                                      and getting user based recommendation) in a batch:

  {
    "requests": [
      {
        "method": "POST",
        "path": "/items/item-24",
        "params": {
          "product_description": "4K TV with 3D feature",
          "categories":   ["Electronics", "Televisions"],
          "price_usd": 342,
          "!cascadeCreate": true
        }
      },
      {
        "method": "POST",
        "path": "/detailviews/",
        "params": {
          "userId": "user-123",
          "itemId": "item-x",
          "timestamp": 1404727253,
          "cascadeCreate": true
        }
      },
      {
        "method": "GET",
        "path": "/recomms/users/user-123/items/",
        "params": {
          "count": 3
        }
      }
    ]
  }
```

---

###### Example Checking the result of the individual requests

You should check that the requests in the Batch succeeded. A request can fail for example due to invalid parameters - the returned error mesage gives you a hint what went wrong.

```js
try {
  const responses = await client.send(new recombee.Batch(reqs));
  for (const response of responses) {
    if (response.code < 200 || response.code > 299) {
      // A request in the Batch did not succeed
      console.log(response);
    }
  }
} catch (error) {
    // The whole Batch request failed
}
```

```kotlin
val result = client.sendAsync(Batch(requests))

result.onSuccess {batchResponses: List<BatchResponse> ->
    // Check individual requests
    batchResponses.forEach { response ->
        if (!response.successful) {
            // A request in the Batch did not succeed
            // response.getResponse() will throw corresponding ApiException
        }

    }
}.onFailure { exception -> // ApiException
    // The whole Batch failed
}
```

```swift
do {
    let responses: [BatchResponse<AnyRecombeeBinding>] = try await client.send(batchRequest)

    // Iterate through each individual batch response
    for responseWrapper in responses {
        if !responseWrapper.isSuccessful {
            // A request in the Batch did not succeed
            // Accessing the response property (responseWrapper.response) will throw the corresponding ClientError
        }
    }
} catch {
    // Handle error for the whole batch request
    print("The entire batch request failed: \(error)")
}
```

```python
responses = client.send(Batch(requests))

for response in responses:

  if not (200 <= response["code"] < 300):
    # A request in the Batch did not succeed
    print(response)
```

```ruby
responses = client.send(Batch.new(requests))

responses.each do |response|
  if response['code'] < 200 || response['code'] > 299
    # A request in the Batch did not succeed
    puts response
  end
end
```

```java
// Send the Batch to the Recombee API
BatchResponse[] responses = client.send(batch);

// Check if the Batch was successful
for (BatchResponse response : responses) {
  if (!response.isSuccessful()) {
    // A request in the Batch did not succeed
    // response.getResponse() will throw corresponding ApiException
  }
}
```

```js
try {
  const responses = await client.send(new rqs.Batch(reqs));

  for (const response of responses) {
    if (response.code < 200 || response.code > 299) {
      // A request in the Batch did not succeed
      console.log(response);
    }
  }
} catch (error) {
  // The whole Batch request failed
}
```

```php
// Send the Batch to the Recombee API
$responses = $client->send($batch);

// Check if the Batch was successful
foreach ($responses as $response) {
  if (200 < $response["code"] || $response["code"] >= 300) {
    // A request in the Batch did not succeed
    print($response);
  }
}
```

```csharp
var responses = client.Send(batch);
for (int i = 0; i < responses.StatusCodes.Length; i++)
{
  if (((int)responses.StatusCodes[i]) < 200 || ((int)responses.StatusCodes[i]) >= 300)
  {
      // A request in the Batch did not succeed
      // Accessing responses[i] will throw corresponding ApiException
  }
}
```

```go
batchRes, err := client.NewBatch(requestsBatch).Send()
if err != nil {
  fmt.Println(err)
  panic(err)
}

for i, resp := range batchRes {
  if resp.StatusCode < 200 || resp.StatusCode >= 300 {
    fmt.Printf("Request #%d failed with status code %d: %s\n", i, resp.StatusCode, resp.Error.ErrorMessage)
  }
}
```

---

###### Example Using distinctRecomms parameter to deduplicate results in multiple boxes

If you show multiple boxes with recommendations on a single page, you may want to ensure that the same item is not recommended in multiple boxes. You can achieve that by specifying `distinctRecomms=true`.

```js
const batchRequest = new rqs.Batch([
  new RecommendItemsToUser('user-id', 5, {scenario:'new_releases', cascadeCreate: true}),
  new RecommendItemsToUser('user-id', 5, {scenario:'just_for_you', cascadeCreate: true})
], {
  distinctRecomms: true
});

const responses = await client.send(batchRequest);
```

```kotlin
val requests = listOf(
    RecommendItemsToUser(userId = "userId", count = 5, scenario = "new_releases", cascadeCreate = true),
    RecommendItemsToUser(userId = "userId", count = 5, scenario = "just_for_you", cascadeCreate = true)
)

val result = client.sendAsync(Batch(requests=requests, distinctRecomms = true))
```

```swift
let requests: [any Request] = [
    RecommendItemsToUser(
        userId: "userId",
        count: 5,
        scenario: "new_releases",
        cascadeCreate: true
    ),
    RecommendItemsToUser(
        userId: "userId",
        count: 5,
        scenario: "just_for_you",
        cascadeCreate: true
    )
]

let batchRequest = Batch(requests: requests, distinctRecomms: true)

let result = try await client.send(batchRequest)
```

```python
requests = [RecommendItemsToUser(user_id, 5, scenario="new_releases", cascade_create=True),
            RecommendItemsToUser(user_id, 5, scenario="just_for_you", cascade_create=True),]
responses = client.send(Batch(requests, distinct_recomms=True))
```

```ruby
batch = Batch.new([
  RecommendItemsToUser.new(user_id, 5, scenario: "new_releases", cascade_create: true),
  RecommendItemsToUser.new(user_id, 5, scenario: "just_for_you", cascade_create: true),
], distinct_recomms: true)

responses = client.send(batch)
```

```java
Request[] requests = new Request[] {
  new RecommendItemsToUser(userId, 5).setScenario("new_releases").setCascadeCreate(true),
  new RecommendItemsToUser(userId, 5).setScenario("just_for_you").setCascadeCreate(true)
};

Batch batch = new Batch(requests).setDistinctRecomms(true);

BatchResponse[] responses = client.send(batch);
```

```js
const batchRequest = new rqs.Batch([
  new RecommendItemsToUser('user-id', 5, {scenario:'new_releases', cascadeCreate: true}),
  new RecommendItemsToUser('user-id', 5, {scenario:'just_for_you', cascadeCreate: true})
], {
  distinctRecomms: true
});

const responses = await client.send(batchRequest);
```

```php
$batchRequest = new Reqs\Batch([
  new Reqs\RecommendItemsToUser('user-id', 5, ['scenario' => 'new_releases', 'cascadeCreate' => true]),
  new Reqs\RecommendItemsToUser('user-id', 5, ['scenario' => 'just_for_you', 'cascadeCreate' => true])
], [
  'distinctRecomms' => true
]);
$replies = $client->send($batchRequest);
```

```csharp
Request[] requests = new Request[] {
    new RecommendItemsToUser(userId, 5, scenario: "new_releases", cascadeCreate: true),
    new RecommendItemsToUser(userId, 5, scenario: "just_for_you", cascadeCreate: true)
};

BatchResponse batchResponse = await client.SendAsync(new Batch(requests, distinctRecomms: true));
```

```go
batchRes, err := client.NewBatch([]requests.Request{
  client.NewRecommendItemsToUser(userId, 5).SetScenario("new_releases").SetCascadeCreate(true),
  client.NewRecommendItemsToUser(userId, 5).SetScenario("just_for_you").SetCascadeCreate(true),
}).SetDistinctRecomms(true).Send()
```

```http
{
  "requests": [
    {
      "method": "GET",
      "path": "/recomms/users/user-123/items/",
      "params": {
        "count": 3,
        "scenario": "recent_releases"
      }
    },
    {
      "method": "GET",
      "path": "/recomms/users/user-123/items/",
      "params": {
        "count": 3,
        "scenario": "just_for_you"
      }
    }
  ],
  "distinctRecomms": true
}
```

##### Notes

Executing the requests in a Batch is equivalent as if they were executed one-by-one individually; there are, however, many optimizations to make batch execution as fast as possible.

The status code of the Batch request itself is 200 even if the individual requests result in error – you have to inspect the code values in the resulting array.

If the status code of the whole batch is not 200, then there is an error in the Batch request itself; in such a case, the error message returned should help you to resolve the problem.

The batch size is limited to 10,000 requests when sent from the server side; if you wish to execute even larger number of requests, please split the Batch into multiple parts. Client libraries do the splitting automatically.

In case of the client side integration, the limit is 30 requests and only the requests that can be called from the client side are allowed.

get

#### List Scenarios

Get all [Scenarios](https://docs.recombee.com/scenarios) of the given database.

```js
const result = await client.send(new requests.ListScenarios());
```

```python
result = client.send(ListScenarios())
```

```ruby
result = client.send(ListScenarios.new())
```

```java
Scenario[] result = client.send(new ListScenarios());
```

```php
$result = $client->send(new Reqs\ListScenarios());
```

```csharp
IEnumerable<Scenario> result = client.Send(new ListScenarios());
```

```go
request := client.NewListScenarios()

result, err := request.Send() // result is of the type []bindings.Scenario
```

```http
GET /{databaseId}/scenarios/
```

---

Since version

5.1.0

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

##### Responses

200

Successful operation.

```
[
  {
    "id": "relatedArticles",
    "endpoint": "recommendItemsToItem"
  },
  {
    "id": "justForYou",
    "endpoint": "recommendItemsToUser"
  },
  {
    "id": "homepageSectionsOrdering",
    "endpoint": "recommendItemSegmentsToUser"
  },
  {
    "id": "homepageSectionContent",
    "endpoint": "recommendItemsToItemSegment"
  }
]
```

---

delete

#### Reset Database

Completely erases all your data, including items, item properties, series, user database, purchases, ratings, detail views, and bookmarks. Make sure the request is never executed in the production environment! Resetting your database is irreversible.

```js
client.send(new requests.ResetDatabase());
```

```python
client.send(ResetDatabase())
```

```ruby
client.send(ResetDatabase.new())
```

```java
client.send(new ResetDatabase());
```

```php
$client->send(new Reqs\ResetDatabase());
```

```csharp
client.Send(new ResetDatabase());
```

```go
request := client.NewResetDatabase()

_, err := request.Send()
```

```http
DELETE /{databaseId}/
```

---

##### Parameters

databaseId

String

Located in: **path**

Required: **Yes**

ID of your database.

---

##### Responses

200

Successful operation.

---

**Table of contents**

* [Items](#items)  
   * [Add Item](#add-item)  
   * [Delete Item](#delete-item)  
   * [List Items](#list-items)  
   * [Delete More Items](#delete-more-items)
* [Item Properties](#item-properties)  
   * [Item properties definition](#item-properties-definition)  
         * [Add Item Property](#add-item-property)  
         * [Delete Item Property](#delete-item-property)  
         * [Get Item Property Info](#get-item-property-info)  
         * [List Item Properties](#list-item-properties)  
   * [Values of item properties](#values-of-item-properties)  
         * [Set Item Values](#set-item-values)  
         * [Get Item Values](#get-item-values)  
         * [Update More Items](#update-more-items)
* [Users](#users)  
   * [Add User](#add-user)  
   * [Delete User](#delete-user)  
   * [Merge Users](#merge-users)  
   * [List Users](#list-users)
* [User Properties](#user-properties)  
   * [User properties definition](#user-properties-definition)  
         * [Add User Property](#add-user-property)  
         * [Delete User Property](#delete-user-property)  
         * [Get User Property Info](#get-user-property-info)  
         * [List User Properties](#list-user-properties)  
   * [Values of user properties](#values-of-user-properties)  
         * [Set User Values](#set-user-values)  
         * [Get User Values](#get-user-values)
* [User-Item Interactions](#user-item-interactions)  
   * [Detail Views](#detail-views)  
         * [Add Detail View](#add-detail-view)  
         * [Delete Detail View](#delete-detail-view)  
         * [List Item Detail Views](#list-item-detail-views)  
         * [List User Detail Views](#list-user-detail-views)  
   * [Purchases](#purchases)  
         * [Add Purchase](#add-purchase)  
         * [Delete Purchase](#delete-purchase)  
         * [List Item Purchases](#list-item-purchases)  
         * [List User Purchases](#list-user-purchases)  
   * [Ratings](#ratings)  
         * [Add Rating](#add-rating)  
         * [Delete Rating](#delete-rating)  
         * [List Item Ratings](#list-item-ratings)  
         * [List User Ratings](#list-user-ratings)  
   * [Cart Additions](#cart-additions)  
         * [Add Cart Addition](#add-cart-addition)  
         * [Delete Cart Addition](#delete-cart-addition)  
         * [List Item Cart Additions](#list-item-cart-additions)  
         * [List User Cart Additions](#list-user-cart-additions)  
   * [Bookmarks](#bookmarks)  
         * [Add Bookmark](#add-bookmark)  
         * [Delete Bookmark](#delete-bookmark)  
         * [List Item Bookmarks](#list-item-bookmarks)  
         * [List User Bookmarks](#list-user-bookmarks)  
   * [View Portions](#view-portions)  
         * [Set View Portion](#set-view-portion)  
         * [Delete View Portion](#delete-view-portion)  
         * [List Item View Portions](#list-item-view-portions)  
         * [List User View Portions](#list-user-view-portions)
* [Recommendations](#recommendations)  
   * [Recommending Items](#recommending-items)  
         * [Recommend Items to User](#recommend-items-to-user)  
         * [Recommend Items to Item](#recommend-items-to-item)  
         * [Recommend Items to Item Segment](#recommend-items-to-item-segment)  
         * [Recommend Next Items](#recommend-next-items)  
   * [Recommending Item Segments](#recommending-item-segments)  
         * [Recommend Item Segments to User](#recommend-item-segments-to-user)  
         * [Recommend Item Segments to Item](#recommend-item-segments-to-item)  
         * [Recommend Item Segments to Item Segment](#recommend-item-segments-to-item-segment)  
         * [Recommend Next Item Segments](#recommend-next-item-segments)  
   * [Recommending Users](#recommending-users)  
         * [Recommend Users to User](#recommend-users-to-user)  
         * [Recommend Users to Item](#recommend-users-to-item)  
   * [Composite Recommendations](#composite-recommendations)  
         * [Composite Recommendation](#composite-recommendation)
* [Search](#search)  
   * [Search Items](#search-items)  
   * [Search Item Segments](#search-item-segments)  
   * [Synonyms](#synonyms)  
         * [Add Search Synonym](#add-search-synonym)  
         * [List Search Synonyms](#list-search-synonyms)  
         * [Delete All Search Synonyms](#delete-all-search-synonyms)  
         * [Delete Search Synonym](#delete-search-synonym)
* [Series](#series)  
   * [Series definition](#series-definition)  
         * [Add Series](#add-series)  
         * [Delete Series](#delete-series)  
         * [List Series](#list-series)  
   * [Series items](#series-items)  
         * [List Series Items](#list-series-items)  
         * [Insert to Series](#insert-to-series)  
         * [Remove from Series](#remove-from-series)
* [Segmentations Definition](#segmentations-definition)  
   * [Property Based Segmentation](#property-based-segmentation)  
         * [Create Property Based Segmentation](#create-property-based-segmentation)  
         * [Update Property Based Segmentation](#update-property-based-segmentation)  
   * [Manual ReQL Segmentation](#manual-reql-segmentation)  
         * [Create Manual ReQL Segmentation](#create-manual-reql-segmentation)  
         * [Update Manual ReQL Segmentation](#update-manual-reql-segmentation)  
         * [Add Manual ReQL Segment](#add-manual-reql-segment)  
         * [Update Manual ReQL Segment](#update-manual-reql-segment)  
         * [Delete Manual ReQL Segment](#delete-manual-reql-segment)  
   * [Auto ReQL Segmentation](#auto-reql-segmentation)  
         * [Create Auto ReQL Segmentation](#create-auto-reql-segmentation)  
         * [Update Auto ReQL Segmentation](#update-auto-reql-segmentation)  
   * [General](#general)  
         * [List Segmentations](#list-segmentations)  
         * [Get Segmentation](#get-segmentation)  
         * [Delete Segmentation](#delete-segmentation)
* [Miscellaneous](#miscellaneous)  
   * [Batch](#batch)  
   * [List Scenarios](#list-scenarios)  
   * [Reset Database](#reset-database)

[Tutorial](/tutorial)

[Admin UI](/admin_ui)