Recombee Docs
Visit recombee.comStart Free
User Documentation
Admin UI
ReQL
API Clients & Integrations
Scenario Recipes
Misc

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 of your database
  • API consumes: application/json
  • API produces: application/json
  • Authentication: HMAC (already implemented in the SDKs)
  • OpenAPI definition: YAML | JSON

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

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

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

Copy
Initialization
client.send(new requests.AddItem(itemId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item to be created.


Successful operation.


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


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

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 instead of deleting the item completely.

Copy
Initialization
client.send(new requests.DeleteItem(itemId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item to be deleted.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItems({
  // optional parameters:
  'filter': <string>,
  'count': <integer>,
  'offset': <integer>,
  'returnProperties': <boolean>,
  'includedProperties': <array>
}));

100

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: No

Boolean-returning ReQL expression, which allows you to filter items to be listed. Only the items for which the expression is true will be returned.


Integer
Located in: query
Required: No

The number of items to be listed.


Integer
Located in: query
Required: No

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


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"
    }
  ]

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
    }
  ]

Successful operation.

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

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


delete

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 instead of deleting the item completely.

Copy
Initialization
const result = await client.send(new requests.DeleteMoreItems(filter));

3.3.0

1000

String
Located in: path
Required: Yes
Since version: 3.3.0

ID of your database.


String
Located in: body
Required: Yes
Since version: 3.3.0

A ReQL expression, which returns true for the items that shall be updated.


Successful operation.

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

Invalid filter.


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

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.

Copy
Initialization
client.send(new requests.AddItemProperty(propertyName, type, {
  // optional parameters:
  'role': <string / Object>,
  'metadata': <array>
}));

String
Located in: path
Required: Yes

ID of your database.


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.


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.


String
Object
Located in: body
Required: No
Since version: 6.3.0

Role to assign to the property.


Array
Located in: body
Required: No
Since version: 6.3.0

List of metadata entries to assign to the property.


Successful operation.


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.


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

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

Copy
Initialization
client.send(new requests.DeleteItemProperty(propertyName));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

Name of the property to be deleted.


Successful operation.


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


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

Gets information about specified item property.

Copy
Initialization
const result = await client.send(new requests.GetItemPropertyInfo(propertyName));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

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


Successful operation.

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

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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemProperties());

String
Located in: path
Required: Yes

ID of your database.


Successful operation.

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

Invalid URL.


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 for filtering and boosting according to your business rules.

post

Sets/updates (some) property values of the given item. The properties (columns) must be previously created by Add item property.

Copy
Initialization
client.send(new requests.SetItemValues(itemId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


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.


Successful operation.


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


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

Gets all the current property values of the given item.

Copy
Initialization
const result = await client.send(new requests.GetItemValues(itemId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item whose properties are to be obtained.


Successful operation.

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

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


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

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}
  }
Copy
Initialization
const result = await client.send(new requests.UpdateMoreItems(filter, changes));

3.3.0

String
Located in: path
Required: Yes
Since version: 3.3.0

ID of your database.


String
Located in: body
Required: Yes
Since version: 3.3.0

A ReQL expression, which returns true for the items that shall be updated.


Object
Located in: body
Required: Yes
Since version: 3.3.0

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


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

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

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


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


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

put

Adds a new user to the database.

Copy
Initialization
client.send(new requests.AddUser(userId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the user to be added.


Successful operation.


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


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

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.

Copy
Initialization
client.send(new requests.DeleteUser(userId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the user to be deleted.


Successful operation.


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


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

Copy
Initialization
client.send(new recombee.MergeUsers(targetUserId, sourceUserId, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

100

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the target user.


String
Located in: path
Required: Yes

ID of the source user.


Boolean
Located in: query
Required: No

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


Successful operation.


The sourceUserId or targetUserId does not match ^[a-zA-Z0-9_-:@.]+$


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

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

Copy
Initialization
const result = await client.send(new requests.ListUsers({
  // optional parameters:
  'filter': <string>,
  'count': <integer>,
  'offset': <integer>,
  'returnProperties': <boolean>,
  'includedProperties': <array>
}));

100

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: No

Boolean-returning ReQL expression, which allows you to filter users to be listed. Only the users for which the expression is true will be returned.


Integer
Located in: query
Required: No

The number of users to be listed.


Integer
Located in: query
Required: No

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


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"
    }
  ]

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"
    }
  ]

Successful operation.

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

Invalid URL.


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

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.

Copy
Initialization
client.send(new requests.AddUserProperty(propertyName, type, {
  // optional parameters:
  'role': <string / Object>,
  'metadata': <array>
}));

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


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.


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.


String
Object
Located in: body
Required: No

Role to assign to the property.


Array
Located in: body
Required: No

List of metadata entries to assign to the property.


Successful operation.


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.


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

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

Copy
Initialization
client.send(new requests.DeleteUserProperty(propertyName));

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 1.3.0

Name of the property to be deleted.


Successful operation.


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


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

Gets information about specified user property.

Copy
Initialization
const result = await client.send(new requests.GetUserPropertyInfo(propertyName));

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 1.3.0

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


Successful operation.

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

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


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

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

Copy
Initialization
const result = await client.send(new requests.ListUserProperties());

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


Successful operation.

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

Invalid URL.


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.

post

Sets/updates (some) property values of the given user. The properties (columns) must be previously created by Add user property.

Copy
Initialization
client.send(new requests.SetUserValues(userId, values, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


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.


Successful operation.


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


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

Gets all the current property values of the given user.

Copy
Initialization
const result = await client.send(new requests.GetUserValues(userId));

1.3.0

String
Located in: path
Required: Yes
Since version: 1.3.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 1.3.0

ID of the user whose properties are to be obtained.


Successful operation.

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

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


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.


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

post
Allowed on Client-Side

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

Copy
Initialization
client.send(new recombee.AddDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'duration': <integer>,
  'cascadeCreate': <boolean>,
  'recommId': <string>,
  'additionalData': <Object>,
  'autoPresented': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: body
Required: Yes

User who viewed the item


String
Located in: body
Required: Yes

Viewed item


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.


Integer
Located in: body
Required: No

Duration of the view


Boolean
Located in: body
Required: No

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


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.


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.


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.


Successful operation.


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


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.


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

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.

Copy
Initialization
client.send(new requests.DeleteDetailView(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: Yes

ID of the user who made the detail view.


String
Located in: query
Required: Yes

ID of the item whose details were viewed.


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.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemDetailViews(itemId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

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


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
  }
]

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


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

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

Copy
Initialization
const result = await client.send(new requests.ListUserDetailViews(userId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

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


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
  }
]

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


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.


post
Allowed on Client-Side

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

Copy
Initialization
client.send(new recombee.AddPurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'profit': <number>,
  'recommId': <string>,
  'additionalData': <Object>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: body
Required: Yes

User who purchased the item


String
Located in: body
Required: Yes

Purchased item


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.


Boolean
Located in: body
Required: No

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


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.


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.


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.


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.


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.


Successful operation.


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


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.


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

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.

Copy
Initialization
client.send(new requests.DeletePurchase(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: Yes

ID of the user who made the purchase.


String
Located in: query
Required: Yes

ID of the item which was purchased.


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.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemPurchases(itemId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item whose purchases are to be listed.


Successful operation.

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

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


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

Lists all the purchases ever made by the given user.

Copy
Initialization
const result = await client.send(new requests.ListUserPurchases(userId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the user whose purchases are to be listed.


Successful operation.

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

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


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.


post
Allowed on Client-Side

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

Copy
Initialization
client.send(new recombee.AddRating(userId, itemId, rating, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>,
  'additionalData': <Object>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: body
Required: Yes

User who submitted the rating


String
Located in: body
Required: Yes

Rated item


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.


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.


Boolean
Located in: body
Required: No

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


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.


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.


Successful operation.


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.


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.


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

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.

Copy
Initialization
client.send(new requests.DeleteRating(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: Yes

ID of the user who rated the item.


String
Located in: query
Required: Yes

ID of the item which was rated.


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.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemRatings(itemId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item whose ratings are to be listed.


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
  }
]

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


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

Lists all the ratings ever submitted by the given user.

Copy
Initialization
const result = await client.send(new requests.ListUserRatings(userId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the user whose ratings are to be listed.


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
  }
]

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


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.


post
Allowed on Client-Side

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

Copy
Initialization
client.send(new recombee.AddCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'amount': <number>,
  'price': <number>,
  'recommId': <string>,
  'additionalData': <Object>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: body
Required: Yes

User who added the item to the cart


String
Located in: body
Required: Yes

Item added to the cart


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.


Boolean
Located in: body
Required: No

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


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.


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.


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.


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.


Successful operation.


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


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.


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

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.

Copy
Initialization
client.send(new requests.DeleteCartAddition(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: Yes

ID of the user who made the cart addition.


String
Located in: query
Required: Yes

ID of the item which was added to the cart.


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.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemCartAdditions(itemId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

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


Successful operation.

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

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


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

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

Copy
Initialization
const result = await client.send(new requests.ListUserCartAdditions(userId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

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


Successful operation.

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

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


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.


post
Allowed on Client-Side

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

Copy
Initialization
client.send(new recombee.AddBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>,
  'additionalData': <Object>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: body
Required: Yes

User who bookmarked the item


String
Located in: body
Required: Yes

Bookmarked item


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.


Boolean
Located in: body
Required: No

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


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.


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.


Successful operation.


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


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.


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

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

Copy
Initialization
client.send(new requests.DeleteBookmark(userId, itemId, {
  // optional parameters:
  'timestamp': <number>
}));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: query
Required: Yes

ID of the user who made the bookmark.


String
Located in: query
Required: Yes

ID of the item which was bookmarked.


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.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemBookmarks(itemId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the item whose bookmarks are to be listed.


Successful operation.

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

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


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

Lists all the bookmarks ever made by the given user.

Copy
Initialization
const result = await client.send(new requests.ListUserBookmarks(userId));

60

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the user whose bookmarks are to be listed.


Successful operation.

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

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


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.


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

Copy
Initialization
client.send(new recombee.SetViewPortion(userId, itemId, portion, {
  // optional parameters:
  'sessionId': <string>,
  'timestamp': <string / number>,
  'cascadeCreate': <boolean>,
  'recommId': <string>,
  'additionalData': <Object>,
  'autoPresented': <boolean>,
  'timeSpent': <number>
}));

2.1.0

String
Located in: path
Required: Yes
Since version: 2.1.0

ID of your database.


String
Located in: body
Required: Yes
Since version: 2.1.0

User who viewed a portion of the item


String
Located in: body
Required: Yes
Since version: 2.1.0

Viewed item


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.


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


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.


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.


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.


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.


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.


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.


Successful operation.


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


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.


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

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

Copy
Initialization
client.send(new requests.DeleteViewPortion(userId, itemId, {
  // optional parameters:
  'sessionId': <string>
}));

2.1.0

1000

String
Located in: path
Required: Yes
Since version: 2.1.0

ID of your database.


String
Located in: query
Required: Yes
Since version: 2.1.0

ID of the user who rated the item.


String
Located in: query
Required: Yes
Since version: 2.1.0

ID of the item which was rated.


String
Located in: query
Required: No
Since version: 2.1.0

Identifier of a session.


Successful operation.


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


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

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

Copy
Initialization
const result = await client.send(new requests.ListItemViewPortions(itemId));

2.1.0

60

String
Located in: path
Required: Yes
Since version: 2.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.1.0

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


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
  }
]

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


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

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

Copy
Initialization
const result = await client.send(new requests.ListUserViewPortions(userId));

2.1.0

60

String
Located in: path
Required: Yes
Since version: 2.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.1.0

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


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
  }
]

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


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.


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").

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

get
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.
  • Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See 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.

Copy
Initialization
const result = await client.send(new recombee.RecommendItemsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}));

2.0.0

String
Located in: path
Required: Yes
Since version: 2.0.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.0.0

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


Integer
Located in: query
Required: Yes
Since version: 2.0.0

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


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 2.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

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.


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.


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.


Successful operation.

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

userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.


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
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.
  • Get subsequent recommended items when the user scrolls down (infinite scroll) or goes to the next page. See 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.

Copy
Initialization
const result = await client.send(new recombee.RecommendItemsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}));

2.0.0

String
Located in: path
Required: Yes
Since version: 2.0.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.0.0

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


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.


Integer
Located in: query
Required: Yes
Since version: 2.0.0

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


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 2.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

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.


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.


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.


Successful operation.

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

itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.


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
Allowed on Client-Side

Recommends Items that are the most relevant to a particular Segment from a context Segmentation.

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

Copy
Initialization
const result = await client.send(new recombee.RecommendItemsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>,
  'minRelevance': <string>,
  'rotationRate': <number>,
  'rotationTime': <number>
}));

5.0.0

String
Located in: path
Required: Yes
Since version: 5.0.0

ID of your database.


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.


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.


Integer
Located in: query
Required: Yes
Since version: 5.0.0

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


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 5.0.0

Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 5.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

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.


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.


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.


successful operation

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-176"
    },
    {
      "id": "item-141"
    },
    {
      "id": "item-967"
    }
  ],
  "numberNextRecommsCalls": 0
}

count is not a positive integer.


contextSegmentId not found in the context segmentation


get
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:

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.

Copy
Initialization
const result = await client.send(new recombee.RecommendNextItems(recommId, count));

3.1.0

String
Located in: path
Required: Yes
Since version: 3.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 3.1.0

ID of the base recommendation request for which next recommendations should be returned


Integer
Located in: query
Required: Yes
Since version: 3.1.0

Number of items to be recommended


Successful operation.

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "item-176"
    },
    {
      "id": "item-141"
    },
    {
      "id": "item-967"
    }
  ],
  "numberNextRecommsCalls": 4
}

Parameter count is not given or is not a positive integer. Parameter recommId is not an UUID.


Base request with the given recommId does not exist or has expired.


Recommendation endpoints that return the Item Segments (categories, genres, artists, etc.).

get
Allowed on Client-Side

Recommends the top Segments from a Segmentation 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 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.

Copy
Initialization
const result = await client.send(new recombee.RecommendItemSegmentsToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

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


Integer
Located in: query
Required: Yes
Since version: 4.1.0

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


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 in the Admin UI. 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.


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.


String
Located in: query
Required: No
Since version: 4.1.0

Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.


String
Located in: query
Required: No
Since version: 4.1.0

Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.1.0

A dictionary of 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
}

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

Used Segmentation not configured for the scenario. userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer.


userId not found in the database and cascadeCreate is false


get
Allowed on Client-Side

Recommends Segments from a Segmentation 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 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.

Copy
Initialization
const result = await client.send(new recombee.RecommendItemSegmentsToItem(itemId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

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


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.


Integer
Located in: query
Required: Yes
Since version: 4.1.0

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


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 in the Admin UI. 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.


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.


String
Located in: query
Required: No
Since version: 4.1.0

Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.


String
Located in: query
Required: No
Since version: 4.1.0

Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.1.0

A dictionary of 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
}

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

Used Segmentation not configured for the scenario. itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer.


itemId not found in the database and cascadeCreate is false


get
Allowed on Client-Side

Recommends Segments from a result Segmentation 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 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.

Copy
Initialization
const result = await client.send(new recombee.RecommendItemSegmentsToItemSegment(contextSegmentId, targetUserId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


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.


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.


Integer
Located in: query
Required: Yes
Since version: 4.1.0

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


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 in the Admin UI. 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.


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.


String
Located in: query
Required: No
Since version: 4.1.0

Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.


String
Located in: query
Required: No
Since version: 4.1.0

Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.1.0

A dictionary of 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
}

successful operation

{
  "recommId": "5fbd94fa-2553-422c-bdb5-af82687d8c6a",
  "recomms": [
    {
      "id": "category-rap"
    },
    {
      "id": "category-dnb"
    },
    {
      "id": "category-electronic"
    }
  ],
  "numberNextRecommsCalls": 0
}

count is not a positive integer.


contextSegmentId not found in the context segmentation


get
Allowed on Client-Side

Returns Item Segments 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:

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.

Copy
Initialization
const result = await client.send(new recombee.RecommendNextItemSegments(recommId, count));

6.2.0

String
Located in: path
Required: Yes
Since version: 6.2.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 6.2.0

ID of the base recommendation request for which next recommendations should be returned


Integer
Located in: query
Required: Yes
Since version: 6.2.0

Number of item segments to be recommended


Successful operation.

{
  "recommId": "768448ea-10b3-4028-bb76-4b2f95121d19",
  "recomms": [
    {
      "id": "Comedy"
    },
    {
      "id": "Drama"
    },
    {
      "id": "Action"
    }
  ],
  "numberNextRecommsCalls": 4
}

Parameter count is not given or is not a positive integer. Parameter recommId is not an UUID.


Base request with the given recommId does not exist or has expired.


Recommendation endpoints that return the Users.

get

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

Copy
Initialization
const result = await client.send(new requests.RecommendUsersToUser(userId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>,
  'rotationRate': <number>,
  'rotationTime': <number>
}));

2.0.0

String
Located in: path
Required: Yes
Since version: 2.0.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.0.0

User to whom we find similar users


Integer
Located in: query
Required: Yes
Since version: 2.0.0

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


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended users based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 2.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

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.


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.


Successful operation.

{
  "recommId": "f88d970d-561c-460f-b4d4-faf0478244ca",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}

userId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.


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

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

Copy
Initialization
const result = await client.send(new requests.RecommendUsersToItem(itemId, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

2.0.0

String
Located in: path
Required: Yes
Since version: 2.0.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 2.0.0

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


Integer
Located in: query
Required: Yes
Since version: 2.0.0

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


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended users based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 2.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

Successful operation.

{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "recomms": [
    {
      "id": "user-64"
    },
    {
      "id": "user-42"
    },
    {
      "id": "user-23"
    }
  ],
  "numberNextRecommsCalls": 0
}

itemId does not match ^[a-zA-Z0-9_-:@.]+$, count is not a positive integer, filter or booster is not valid ReQL expressions, filter expression does not return boolean, booster does not return double or integer.


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 return a source entity (e.g., an Item, or Item Segment) 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
Allowed on Client-Side

Composite Recommendation returns both a source entity (e.g., an Item or Item Segment) 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.

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:

Since the first step uses Recommend Item Segments 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 and resultSettings. In the example above:

See this example for more details.

Copy
Initialization
const result = await client.send(new recombee.CompositeRecommendation(scenario, count, {
  // optional parameters:
  'itemId': <string>,
  'userId': <string>,
  'logic': <string / Object>,
  'segmentId': <string>,
  'searchQuery': <string>,
  'cascadeCreate': <boolean>,
  'sourceSettings': <Object>,
  'resultSettings': <Object>
}));

6.0.0

String
Located in: path
Required: Yes
Since version: 6.0.0

ID of your database.


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 in the Admin UI. 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.


Integer
Located in: body
Required: Yes
Since version: 6.0.0

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


String
Located in: body
Required: No
Since version: 6.0.0

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


String
Located in: body
Required: No
Since version: 6.0.0

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


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 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 in the Admin UI.


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.


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.


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.


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.


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.


Successful operation.

{
  "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed",
  "source": {
    "id": "category-4"
  },
  "recomms": [
    {
      "id": "item-64"
    },
    {
      "id": "item-42"
    },
    {
      "id": "item-23"
    }
  ],
  "numberNextRecommsCalls": 0
}

Count is not a positive integer, provided scenario not found.


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.


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 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:

Copy
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);

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:

Copy
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);

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
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.
  • Get subsequent search results when the user scrolls down or goes to the next page. See 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.

Copy
Initialization
const result = await client.send(new recombee.SearchItems(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'returnProperties': <boolean>,
  'includedProperties': <array>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

3.0.0

String
Located in: path
Required: Yes
Since version: 3.0.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 3.0.0

ID of the user for whom personalized search will be performed.


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.


Integer
Located in: query
Required: Yes
Since version: 3.0.0

Number of items to be returned (N for the top-N results).


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 in the Admin UI. 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.


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.


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
  }

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
  }

String
Located in: query
Required: No
Since version: 2.0.0

Boolean-returning ReQL expression, which allows you to filter recommended items based on the values of their attributes.

Filters can also be assigned to a scenario in the Admin UI.


String
Located in: query
Required: No
Since version: 2.0.0

Number-returning 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 in the Admin UI.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.0.0

A dictionary of 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
}

Successful operation.

{
  "recommId": "4fd901fe-4ba1-a3f1-a690-f4f01f76d4eb",
  "recomms": [
    {
      "id": "item-476"
    },
    {
      "id": "item-412"
    },
    {
      "id": "item-773"
    }
  ],
  "numberNextRecommsCalls": 0
}

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 expressions, filter expression does not return boolean, booster does not return double or integer.


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

Copy
Initialization
const result = await client.send(new recombee.SearchItemSegments(userId, searchQuery, count, {
  // optional parameters:
  'scenario': <string>,
  'cascadeCreate': <boolean>,
  'filter': <string>,
  'booster': <string>,
  'logic': <string / Object>,
  'reqlExpressions': <Object>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the user for whom personalized search will be performed.


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.


Integer
Located in: query
Required: Yes
Since version: 4.1.0

Number of segments to be returned (N for the top-N results).


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 in the Admin UI. 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.


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.


String
Located in: query
Required: No
Since version: 4.1.0

Boolean-returning ReQL expression which allows you to filter recommended segments based on the segmentationId.


String
Located in: query
Required: No
Since version: 4.1.0

Number-returning ReQL expression which allows you to boost recommendation rate of some segments based on the segmentationId.


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 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 in the Admin UI.


Object
Located in: query
Required: No
Since version: 6.1.0

A dictionary of 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
}

successful operation

{
  "recommId": "7acdc8b5-f731-44f8-b522-72625044666f",
  "recomms": [
    {
      "id": "cell phones"
    },
    {
      "id": "cell phone accessories"
    }
  ],
  "numberNextRecommsCalls": 0
}

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 expressions, filter expression does not return boolean, booster does not return double or integer.


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.


Define that some words or phrases should be considered equal by the full-text search engine.

post

Adds a new synonym for the 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.

Copy
Initialization
const result = await client.send(new requests.AddSearchSynonym(term, synonym, {
  // optional parameters:
  'oneWay': <boolean>
}));

3.2.0

1000

String
Located in: path
Required: Yes
Since version: 3.2.0

ID of your database.


String
Located in: body
Required: Yes
Since version: 3.2.0

A word to which the synonym is specified.


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.


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.


Successful operation. Returns data about the added synonym (including id).

{
  "id": "cc198c86-e015-bb74-b5f4-8f996fd26736",
  "term": "sci-fi",
  "synonym": "science fiction",
  "oneWay": false
}

Missing a field, or a field has a wrong type.


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

Gives the list of synonyms defined in the database.

Copy
Initialization
const result = await client.send(new requests.ListSearchSynonyms({
  // optional parameters:
  'count': <integer>,
  'offset': <integer>
}));

60

String
Located in: path
Required: Yes

ID of your database.


Integer
Located in: query
Required: No

The number of synonyms to be listed.


Integer
Located in: query
Required: No

Specifies the number of synonyms to skip (ordered by term).


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

Deletes all synonyms defined in the database.

Copy
Initialization
client.send(new requests.DeleteAllSearchSynonyms());

60

String
Located in: path
Required: Yes

ID of your database.


Successful operation.


delete

Deletes synonym of the given id. This synonym is no longer taken into account in the Search items.

Copy
Initialization
client.send(new requests.DeleteSearchSynonym(id));

1000

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the synonym that should be deleted.


Successful operation.


Synonym with the given id does not exist.


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.

Methods for managing series - creating, listing, and deleting them.

put

Creates a new series in the database.

Copy
Initialization
client.send(new requests.AddSeries(seriesId, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the series to be created.


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.


Successful operation.


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


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

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!

Copy
Initialization
client.send(new requests.DeleteSeries(seriesId, {
  // optional parameters:
  'cascadeDelete': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the series to be deleted.


Boolean
Located in: body
Required: No

If set to true, item with the same ID as seriesId will be also deleted. Default is false.


Successful operation.


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


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

Gets the list of all the series currently present in the database.

Copy
Initialization
const result = await client.send(new requests.ListSeries());

100

String
Located in: path
Required: Yes

ID of your database.


Successful operation.

[
  "series-1",
  "series-2",
  "series-3"
]

Invalid URL.


Methods for adding items (or even series themselves) to series.

get

Lists all the items present in the given series, sorted according to their time index values.

Copy
Initialization
const result = await client.send(new requests.ListSeriesItems(seriesId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the series whose items are to be listed.


Successful operation.

[
  {
    "itemType": "item",
    "itemId": "item-x",
    "time": 1
  },
  {
    "itemType": "item",
    "itemId": "item-y",
    "time": 2
  },
  {
    "itemType": "item",
    "itemId": "item-z",
    "time": 3
  }
]

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


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

Inserts an existing item/series into a series of the given seriesId at a position determined by time.

Copy
Initialization
client.send(new requests.InsertToSeries(seriesId, itemType, itemId, time, {
  // optional parameters:
  'cascadeCreate': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the series to be inserted into.


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.


String
Located in: body
Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.


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.


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.


Successful operation.


seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$, or itemType∉{item,series}, or time is not a real number.


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.


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

Removes an existing series item from the series.

Copy
Initialization
client.send(new requests.RemoveFromSeries(seriesId, itemType, itemId));

String
Located in: path
Required: Yes

ID of your database.


String
Located in: path
Required: Yes

ID of the series from which a series item is to be removed.


String
Located in: body
Required: Yes

Type of the item to be removed.


String
Located in: body
Required: Yes

ID of the item iff itemType is item. ID of the series iff itemType is series.


Successful operation.


The seriesId or itemId does not match ^[a-zA-Z0-9_-:@.]+$ or itemType∉{item, series}.


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 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 for more info.

Property-based Segmentation groups the Items by the value of a particular property. See this section for more info.

put

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.

Copy
Initialization
client.send(new requests.CreatePropertyBasedSegmentation(segmentationId, sourceType, propertyName, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the newly created Segmentation


String
Located in: body
Required: Yes
Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.


String
Located in: body
Required: Yes
Since version: 4.1.0

Name of the property on which the Segmentation should be based


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, property is not of supported type (string or set).


Property does not exist.


post

Updates a Property Based Segmentation

Copy
Initialization
client.send(new requests.UpdatePropertyBasedSegmentation(segmentationId, {
  // optional parameters:
  'propertyName': <string>,
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the updated Segmentation


String
Located in: body
Required: No
Since version: 4.1.0

Name of the property on which the Segmentation should be based


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, property is not of supported type (string or set).


Property does not exist. Segmentation with given ID does not exist.


Segmentation whose Segments are defined by ReQL filters. See this section for more info.

put

Segment the items using multiple ReQL filters.

Use the Add Manual ReQL Items Segment endpoint to create the individual segments.

Copy
Initialization
client.send(new requests.CreateManualReqlSegmentation(segmentationId, sourceType, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the newly created Segmentation


String
Located in: body
Required: Yes
Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


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


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 for more info.

Copy
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))
post

Update an existing Segmentation.

Copy
Initialization
client.send(new requests.UpdateManualReqlSegmentation(segmentationId, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the updated Segmentation


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


segmentationId does not match ^[a-zA-Z0-9_-:@.]+$. Given Segmentation is of different type.


Segmentation with given ID does not exist.


put

Adds a new Segment into a Manual ReQL Segmentation.

The new Segment is defined by a ReQL filter that returns true for an item in case that this item belongs to the segment.

Copy
Initialization
client.send(new requests.AddManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  'title': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segmentation to which the new Segment should be added


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the newly created Segment


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.


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.


successful operation


segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.


Segmentation with given ID does not exist.


post

Update definition of the Segment.

Copy
Initialization
client.send(new requests.UpdateManualReqlSegment(segmentationId, segmentId, filter, {
  // optional parameters:
  'title': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segmentation to which the updated Segment belongs


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segment that will be updated


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.


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.


successful operation


segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.


Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation.


delete

Delete a Segment from a Manual ReQL Segmentation.

Copy
Initialization
client.send(new requests.DeleteManualReqlSegment(segmentationId, segmentId));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segmentation from which the Segment should be deleted


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segment that should be deleted


successful operation


segmentationId or segmentId does not match ^[a-zA-Z0-9_-:@.]+$. Segmentation is of wrong type.


Segmentation with given ID does not exist. Segment with given ID does not exist in the 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 for more info.

put

Segment the items using a ReQL expression.

For each item, the expression should return a set that contains IDs of segments to which the item belongs to.

Copy
Initialization
client.send(new requests.CreateAutoReqlSegmentation(segmentationId, sourceType, expression, {
  // optional parameters:
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the newly created Segmentation


String
Located in: body
Required: Yes
Since version: 4.1.0

What type of data should be segmented. Currently only items are supported.


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


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


segmentationId does not match ^[a-zA-Z0-9_-:@.]+$, ReQL expression is invalid.


Create a Segmentation, whose Segments combine the country of origin and the genre.

See this section for more info.

Copy
req = CreateAutoReqlSegmentation(
    "country-and-genre",
    "items",
    "map(lambda 'genre': 'genre' + \"-\" + 'country', 'genres')",
)

response = client.send(req)
post

Update an existing Segmentation.

Copy
Initialization
client.send(new requests.UpdateAutoReqlSegmentation(segmentationId, {
  // optional parameters:
  'expression': <string>,
  'title': <string>,
  'description': <string>
}));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the updated Segmentation


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


String
Located in: body
Required: No
Since version: 4.1.0

Human-readable name that is shown in the Recombee Admin UI.


String
Located in: body
Required: No
Since version: 4.1.0

Description that is shown in the Recombee Admin UI.


successful operation


segmentationId does not match ^[a-zA-Z0-9_-:@.]+$. ReQL expression is invalid. Given Segmentation is of different type.


Segmentation with given ID does not exist.


get

Return all existing items Segmentations.

Copy
Initialization
const result = await client.send(new requests.ListSegmentations(sourceType));

4.1.0

60

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


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.


{
  "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 existing Segmentation.

Copy
Initialization
const result = await client.send(new requests.GetSegmentation(segmentationId));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segmentation that should be returned


{
  "segmentationId": "category",
  "sourceType": "items",
  "segmentationType": "property",
  "title": "Category Segmentation",
  "description": "Groups items by their category"
}

Segmentation with given ID does not exist.


delete

Delete existing Segmentation.

Copy
Initialization
client.send(new requests.DeleteSegmentation(segmentationId));

4.1.0

String
Located in: path
Required: Yes
Since version: 4.1.0

ID of your database.


String
Located in: path
Required: Yes
Since version: 4.1.0

ID of the Segmentation that should be deleted


successful operation


Segmentation with given ID does not exist.


post
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).

Copy
Initialization
const result = await client.send(new recombee.Batch(requests, {
  // optional parameters:
  'distinctRecomms': <boolean>
}));

String
Located in: path
Required: Yes

ID of your database.


Array
Located in: body
Required: Yes

JSON array containing the requests.


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.


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
    }
  }
]

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.


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.


Too large batch (containing more than 10,000 requests in case of a server side request).


Batch can encapsulate requests of various types.

Copy
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));

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.

Copy
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
}

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.

Copy
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);

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

Get all Scenarios of the given database.

Copy
Initialization
const result = await client.send(new requests.ListScenarios());

5.1.0

String
Located in: path
Required: Yes

ID of your database.


Successful operation.

[
  {
    "id": "relatedArticles",
    "endpoint": "recommendItemsToItem"
  },
  {
    "id": "justForYou",
    "endpoint": "recommendItemsToUser"
  },
  {
    "id": "homepageSectionsOrdering",
    "endpoint": "recommendItemSegmentsToUser"
  },
  {
    "id": "homepageSectionContent",
    "endpoint": "recommendItemsToItemSegment"
  }
]

delete

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.

Copy
Initialization
client.send(new requests.ResetDatabase());

String
Located in: path
Required: Yes

ID of your database.


Successful operation.


Table of contents
© Copyright 2026, Recombee s.r.o
docs.recombee.com