openapi: 3.0.0 info: title: Recombee API description: > This is the documentation for Recombee Recommendation API (https://docs.recombee.com/api) Authentication details need to be provided with every request to Recombee API. Please refer to [Authentication (HMAC) document](https://docs.recombee.com/authentication) for more information. version: 4.1.0 paths: /{databaseId}/items/{itemId}: put: summary: Add Item description: | Adds new item of the given `itemId` to the items catalog. All the item properties for the newly created items are set to null. tags: - Items parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: ID of the item to be created. required: true schema: type: string responses: '201': description: Successful operation. '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '409': description: >- 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: summary: Delete Item description: > Deletes an item of the given `itemId` from the catalog. If there are any *purchases*, *ratings*, *bookmarks*, *cart additions*, or *detail views* of the item present in the database, they will be deleted in cascade as well. Also, if the item is present in some *series*, it will be removed from all the *series* where present. If an item becomes obsolete/no longer available, it is meaningful to keep it in the catalog (along with all the interaction data, which are very useful), and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely. tags: - Items parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: ID of the item to be deleted. required: true schema: type: string responses: '200': description: Successful operation. '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. post: summary: Set Item Values description: > Sets/updates (some) property values of the given item. The properties (columns) must be previously created by [Add item property](https://docs.recombee.com/api#add-item-property). tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item which will be modified. required: true schema: type: string - name: cascadeCreate in: query description: Sets whether the item should be created if not present in the database. required: false schema: type: boolean requestBody: content: application/json: schema: type: string description: | The values for the individual properties. Example of the body: ```json { "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: ```json { "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. required: true responses: '200': description: Successful operation. '400': description: | Property name does not match ''^[a-zA-Z0-9_\-:]+$'', value does not match the property type. '404': description: > 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: summary: Get Item Values description: | Gets all the current property values of the given item. tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose properties are to be obtained. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: object additionalProperties: {} examples: response: value: release-date: null tags: - electronics - laptops num-processors: 12 description: Very powerful laptop weight: 1.6 '400': description: The *itemId* does not match ^[a-zA-Z0-9_\-:@\.]+$ '404': description: > 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. /{databaseId}/items/list/: get: summary: List Items description: Gets a list of IDs of items currently present in the catalog. tags: - Items parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: filter in: query description: >- Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter items to be listed. Only the items for which the expression is *true* will be returned. required: false schema: type: string - name: count in: query description: The number of items to be listed. required: false schema: type: integer - name: offset in: query description: Specifies the number of items to skip (ordered by `itemId`). required: false schema: type: integer - name: returnProperties in: query description: > With `returnProperties=true`, property values of the listed items are returned along with their IDs in a JSON dictionary. Example response: ```json [ { "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" } ] ``` required: false schema: type: boolean - name: includedProperties in: query description: > 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`: ```json [ { "itemId": "tv-178", "description": "4K TV with 3D feature", "price": 342 }, { "itemId": "mixer-42", "description": "Stainless Steel Mixer", "price": 39 } ] ``` required: false style: form explode: false schema: type: array items: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Item' examples: response: value: - item-1 - item-2 - item-3 '404': description: If present, `filter` contains a non-existing item property. /{databaseId}/items/properties/{propertyName}: put: summary: Add Item Property description: > 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. tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: > 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. required: true schema: type: string - name: type in: query description: > 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. * `set` - Set of strings. * `image` - URL of an image (`jpeg`, `png` or `gif`). * `imageList` - List of URLs that refer to images. required: true schema: type: string enum: - int - double - string - boolean - timestamp - set - image - imageList responses: '201': description: Successful operation. '400': description: > Property name does not match ^[a-zA-Z0-9_\-:]+$, or it is a reserved keyword (''id'', ''itemid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid. '409': description: >- 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: summary: Delete Item Property description: | Deleting an item property is roughly equivalent to removing a column from the table of items. tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: Name of the property to be deleted. required: true schema: type: string responses: '200': description: Successful operation. '400': description: Property name does not match ^[a-zA-Z0-9_\-:]+$. '404': description: >- 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: summary: Get Item Property Info description: | Gets information about specified item property. tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: Name of the property about which the information is to be retrieved. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/PropertyInfo' examples: response: value: name: num-processors type: int '400': description: Property name does not match ^[a-zA-Z0-9_\-:]+$. '404': description: >- 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. /{databaseId}/items/properties/list/: get: summary: List Item Properties description: | Gets the list of all the item properties in your database. tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/PropertyInfo' examples: response: value: - name: tags type: set - name: release-date type: timestamp - name: description type: string '404': description: Invalid URL. /{databaseId}/more-items/: post: summary: Update More Items description: | 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* ```json { "filter": "'releaseDate' < now() - 7*24*3600", "changes": {"available": false} } ``` tags: - Item Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateMoreItemsParameters' description: | Filter and changes in item properties. required: true responses: '200': description: Successful operation. Returns IDs of updated items and their count. content: application/json: schema: $ref: '#/components/schemas/UpdateMoreItemsResponse' examples: response: value: itemIds: - item-42 - item-125 - item-11 count: 3 '400': description: | Invalid filter, property name does not match ''^[a-zA-Z0-9_\-:]+$'', value does not match the property type. '404': description: | Property of the given name is not present in the database. delete: summary: Delete More Items description: >- Deletes all the items that pass the filter. If an item becomes obsolete/no longer available, it is meaningful to **keep it in the catalog** (along with all the interaction data, which are very useful) and **only exclude the item from recommendations**. In such a case, use [ReQL filter](https://docs.recombee.com/reql) instead of deleting the item completely. tags: - Items parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DeleteMoreItemsParameters' description: | Example of the body: ```json { "filter": "'releaseDate' < now() - 7*24*3600", } required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/DeleteMoreItemsResponse' examples: response: value: itemIds: - item-42 - item-125 - item-11 count: 3 '400': description: | Invalid filter. /{databaseId}/series/{seriesId}: put: summary: Add Series description: Creates a new series in the database. tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: seriesId in: path description: ID of the series to be created. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/AddSeries' description: | Example of the body: ```json { "cascadeCreate": true } ``` responses: '201': description: Successful operation. '400': description: The `seriesId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '409': description: >- 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: summary: Delete Series description: | 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! tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: seriesId in: path description: ID of the series to be deleted. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DeleteSeries' description: | Example of the body: ```json { "cascadeCreate": true } ``` responses: '200': description: Successful operation. '400': description: The `seriesId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/series/list/: get: summary: List Series description: Gets the list of all the series currently present in the database. tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Series' examples: response: value: - series-1 - series-2 - series-3 '404': description: Invalid URL. /{databaseId}/series/{seriesId}/items/: get: summary: List Series Items description: Lists all the items present in the given series, sorted according to their time index values. tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: seriesId in: path description: ID of the series whose items are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/SeriesItem' examples: response: value: - itemType: item itemId: item-x time: 1 - itemType: item itemId: item-y time: 2 - itemType: item itemId: item-z time: 3 '400': description: The `seriesId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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: summary: Insert to Series description: | Inserts an existing item/series into a series of the given seriesId at a position determined by time. tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: seriesId in: path description: ID of the series to be inserted into. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SeriesItem' description: | Description of the item and position in series\n\n Example of the body: ```json { "itemType": "series", "itemId": "season-1", "time": 1 } ``` required: true responses: '200': description: Successful operation. '400': description: > `seriesId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `itemType`∉{item,series}, or `time` is not a real number. '404': description: > Series of the given `seriesId` is not present in the database. Item of the given `itemId` is not present in the database if `itemType` is item. Series of the given `itemId` is not present in the database if `itemType` is series. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Remove from Series description: Removes an existing series item from the series. tags: - Series parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: seriesId in: path description: ID of the series from which a series item is to be removed. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RemoveSeriesItem' description: | Description of the item and position in series\n\n Example of the body: ```json { "itemType": "series", "itemId": "season-1" } ``` required: true responses: '200': description: Successful operation. '400': description: The `seriesId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$ or `itemType`∉{`item`, `series`}. '404': description: >- 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. /{databaseId}/users/{userId}: put: summary: Add User description: | Adds a new user to the database. tags: - Users parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user to be added. required: true schema: type: string responses: '201': description: Successful operation. '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '409': description: >- 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: summary: Delete User description: > 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. tags: - Users parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user to be deleted. required: true schema: type: string responses: '200': description: Successful operation. '400': description: The *userId* does not match ''^[a-zA-Z0-9_\-:@\.]+$''. '404': description: >- 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. post: summary: Set User Values description: > Sets/updates (some) property values of the given user. The properties (columns) must be previously created by [Add user property](https://docs.recombee.com/api#add-user-property). tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: | ID of the user which will be modified. required: true schema: type: string - name: cascadeCreate in: query description: Sets whether the user should be created if not present in the database. required: false schema: type: boolean requestBody: content: application/json: schema: type: string description: | The values for the individual properties. Example of the body: ```json { "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: ```json { "country": "US", "!cascadeCreate": true } ``` Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names. required: true responses: '200': description: Successful operation. '400': description: | Property name does not match ''^[a-zA-Z0-9_\-:]+$'', value does not agree to property type. '404': description: > 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: summary: Get User Values description: | Gets all the current property values of the given user. tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: | ID of the user whose properties are to be obtained. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: object additionalProperties: {} examples: response: value: country: US sex: F '400': description: The *userId* does not match ^[a-zA-Z0-9_\-:@\.]+$ '404': description: > 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. /{databaseId}/users/{targetUserId}/merge/{sourceUserId}: put: summary: Merge Users description: > 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. tags: - Users parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: targetUserId in: path description: ID of the target user. required: true schema: type: string - name: sourceUserId in: path description: ID of the source user. required: true schema: type: string - name: cascadeCreate in: query description: Sets whether the user *targetUserId* should be created if not present in the database. required: false schema: type: boolean responses: '201': description: Successful operation. '400': description: The *sourceUserId* or *targetUserId* does not match ^[a-zA-Z0-9_\-:@\.]+$ '404': description: >- 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. /{databaseId}/users/list/: get: summary: List Users description: Gets a list of IDs of users currently present in the catalog. tags: - Users parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: filter in: query description: >- Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter users to be listed. Only the users for which the expression is *true* will be returned. required: false schema: type: string - name: count in: query description: The number of users to be listed. required: false schema: type: integer - name: offset in: query description: Specifies the number of users to skip (ordered by `userId`). required: false schema: type: integer - name: returnProperties in: query description: > With `returnProperties=true`, property values of the listed users are returned along with their IDs in a JSON dictionary. Example response: ```json [ { "userId": "user-81", "country": "US", "sex": "M" }, { "userId": "user-314", "country": "CAN", "sex": "F" } ] ``` required: false schema: type: boolean - name: includedProperties in: query description: > 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`: ```json [ { "userId": "user-81", "country": "US" }, { "userId": "user-314", "country": "CAN" } ] ``` required: false style: form explode: false schema: type: array items: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/User' examples: response: value: - user-1 - user-2 - user-3 '404': description: Invalid URL. /{databaseId}/users/properties/{propertyName}: put: summary: Add User Property description: > 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. tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: > 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. required: true schema: type: string - name: type in: query description: > 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. * `set` - Set of strings. required: true schema: type: string enum: - int - double - string - boolean - timestamp - set responses: '201': description: Successful operation. '400': description: > Property name does not match ^[a-zA-Z0-9_\-:]+$, or it is a reserved keyword (''id'', ''userid''), or its length exceeds 63 characters. Type information is missing, or the given type is invalid. '409': description: >- 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: summary: Delete User Property description: | Deleting a user property is roughly equivalent to removing a column from the table of users. tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: Name of the property to be deleted. required: true schema: type: string responses: '200': description: Successful operation. '400': description: Property name does not match ^[a-zA-Z0-9_\-:]+$. '404': description: >- 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: summary: Get User Property Info description: | Gets information about specified user property. tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: propertyName in: path description: Name of the property about which the information is to be retrieved. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/PropertyInfo' examples: response: value: name: country type: string '400': description: Property name does not match ^[a-zA-Z0-9_\-:]+$. '404': description: >- 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. /{databaseId}/users/properties/list/: get: summary: List User Properties description: | Gets the list of all the user properties in your database. tags: - User Properties parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/PropertyInfo' examples: response: value: - name: country type: string - name: sex type: string '404': description: Invalid URL. /{databaseId}/detailviews/: post: summary: Add Detail View description: | Adds a detail view of the given item made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DetailView' description: Detail view description required: true responses: '200': description: Successful operation. '400': description: >- Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. `timestamp` or `duration` is not a real number ≥ 0. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete Detail View description: > 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. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who made the detail view. required: true schema: type: string - name: itemId in: query description: ID of the item whose details were viewed. required: true schema: type: string - name: timestamp in: query description: >- Unix timestamp of the detail view. If the `timestamp` is omitted, then all the detail views with the given `userId` and `itemId` are deleted. schema: type: number format: double responses: '200': description: Successful operation. '400': description: Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `timestamp` is not a real number ≥ 0. '404': description: >- 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. /{databaseId}/items/{itemId}/detailviews/: get: summary: List Item Detail Views description: Lists all the detail views of the given item ever made by different users. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose detail views are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/DetailView' examples: response: value: - itemId: item-x userId: user-a duration: 14.23 autoPresented: true timestamp: 1348151906 - itemId: item-x userId: user-b duration: null autoPresented: false timestamp: 1348239363 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/detailviews/: get: summary: List User Detail Views description: Lists all the detail views of different items ever made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose detail views are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/DetailView' examples: response: value: - itemId: item-y userId: user-a duration: 134.03 autoPresented: true timestamp: 1348139180 - itemId: item-x userId: user-a duration: 14.23 autoPresented: false timestamp: 1348151906 '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/purchases/: post: summary: Add Purchase description: | Adds a purchase of the given item made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Purchase' description: Purchase description required: true responses: '200': description: Successful operation. '400': description: The `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. `timestamp` is not a real number ≥ 0. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete Purchase description: > 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. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who made the purchase. required: true schema: type: string - name: itemId in: query description: ID of the item which was purchased. required: true schema: type: string - name: timestamp in: query description: >- Unix timestamp of the purchase. If the `timestamp` is omitted, then all the purchases with the given `userId` and `itemId` are deleted. schema: type: number format: double responses: '200': description: Successful operation. '400': description: Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `timestamp` is not a real number ≥ 0. '404': description: >- 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. /{databaseId}/items/{itemId}/purchases/: get: summary: List Item Purchases description: Lists all the ever-made purchases of the given item. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose purchases are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Purchase' examples: response: value: - itemId: item-x userId: user-a timestamp: 1348151906 - itemId: item-x userId: user-b timestamp: 1348327154 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/purchases/: get: summary: List User Purchases description: Lists all the purchases ever made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose purchases are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Purchase' examples: response: value: - itemId: item-x timestamp: 1348151906 userId: user-a - itemId: item-z timestamp: 1348239363 userId: user-a '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/ratings/: post: summary: Add Rating description: | Adds a rating of the given item made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Rating' description: Rating description required: true responses: '200': description: Successful operation. '400': description: >- The `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or rating is not a real number from [-1.0,1.0], or timestamp is not a real number ≥ 0. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete Rating description: > 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. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who rated the item. required: true schema: type: string - name: itemId in: query description: ID of the item which was rated. required: true schema: type: string - name: timestamp in: query description: >- Unix timestamp of the rating. If the `timestamp` is omitted, then all the ratings with the given `userId` and `itemId` are deleted. schema: type: number format: double responses: '200': description: Successful operation. '400': description: Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `timestamp` is not a real number ≥ 0. '404': description: >- 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. /{databaseId}/items/{itemId}/ratings/: get: summary: List Item Ratings description: Lists all the ratings of an item ever submitted by different users. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose ratings are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Rating' examples: response: value: - itemId: item-x userId: user-a rating: -0.25 timestamp: 1348151906 - itemId: item-x userId: user-b rating: 0 timestamp: 1348239363 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/ratings/: get: summary: List User Ratings description: Lists all the ratings ever submitted by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose ratings are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Rating' examples: response: value: - itemId: item-y userId: user-a rating: 0.5 timestamp: 1348139180 - itemId: item-x userId: user-a rating: -0.25 timestamp: 1348151906 '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/cartadditions/: post: summary: Add Cart Addition description: | Adds a cart addition of the given item made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CartAddition' description: Cart addition description required: true responses: '200': description: Successful operation. '400': description: The `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, `timestamp` is not a real number ≥ 0. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete Cart Addition description: > 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. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who made the cart addition. required: true schema: type: string - name: itemId in: query description: ID of the item which was added to the cart. required: true schema: type: string - name: timestamp in: query description: >- Unix timestamp of the cart addition. If the `timestamp` is omitted, then all the cart additions with the given `userId` and `itemId` are deleted. schema: type: number format: double responses: '200': description: Successful operation. '400': description: Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `timestamp` is not a real number ≥ 0. '404': description: >- 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. /{databaseId}/items/{itemId}/cartadditions/: get: summary: List Item Cart Additions description: Lists all the ever-made cart additions of the given item. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose cart additions are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/CartAddition' examples: response: value: - itemId: item-x userId: user-a timestamp: 1348151906 - itemId: item-x userId: user-a timestamp: 1348327154 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/cartadditions/: get: summary: List User Cart Additions description: Lists all the cart additions ever made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose cart additions are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/CartAddition' examples: response: value: - itemId: item-x timestamp: 1348151906 userId: user-a - itemId: item-z timestamp: 1348239363 userId: user-a '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/bookmarks/: post: summary: Add Bookmark description: | Adds a bookmark of the given item made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Bookmark' description: Bookmark description required: true responses: '200': description: Successful operation. '400': description: The `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, `timestamp` is not a real number ≥ 0. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete Bookmark description: > Deletes a bookmark uniquely specified by `userId`, `itemId`, and `timestamp` or all the bookmarks with the given `userId` and `itemId` if `timestamp` is omitted. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who made the bookmark. required: true schema: type: string - name: itemId in: query description: ID of the item which was bookmarked. required: true schema: type: string - name: timestamp in: query description: >- Unix timestamp of the bookmark. If the `timestamp` is omitted, then all the bookmarks with the given `userId` and `itemId` are deleted. schema: type: number format: double responses: '200': description: Successful operation. '400': description: Given `userId` or `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or `timestamp` is not a real number ≥ 0. '404': description: >- 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. /{databaseId}/items/{itemId}/bookmarks/: get: summary: List Item Bookmarks description: Lists all the ever-made bookmarks of the given item. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose bookmarks are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Bookmark' examples: response: value: - itemId: item-x userId: user-a timestamp: 1348151906 - itemId: item-x userId: user-a timestamp: 1348327154 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/bookmarks/: get: summary: List User Bookmarks description: Lists all the bookmarks ever made by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose bookmarks are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/Bookmark' examples: response: value: - itemId: item-x timestamp: 1348151906 userId: user-a - itemId: item-z timestamp: 1348239363 userId: user-a '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/viewportions/: post: summary: Set View Portion description: | 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. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ViewPortion' description: View portion description required: true responses: '200': description: Successful operation. '400': description: >- The `userId`, `itemId` or `sessionId` does not match ^[a-zA-Z0-9_\-:@\.]+$, or the `portion` is not a real number from [0.0,1.0]. '404': description: >- The `cascadeCreate` is not set true and the `userId` or the `itemId` were found in the database. If there is no additional info in the JSON response, you probably have an error in your URL. '409': description: >- 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: summary: Delete View Portion description: | Deletes an existing view portion specified by (`userId`, `itemId`, `sessionId`) from the database. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: query description: ID of the user who rated the item. required: true schema: type: string - name: itemId in: query description: ID of the item which was rated. required: true schema: type: string - name: sessionId in: query description: Identifier of a session. schema: type: string responses: '200': description: Successful operation. '400': description: Given `userId`, `itemId` or `sessionId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/items/{itemId}/viewportions/: get: summary: List Item View Portions description: | Lists all the view portions of an item ever submitted by different users. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: | ID of the item whose view portions are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/ViewPortion' examples: response: value: - itemId: item-x userId: user-a sessionId: ABAD1D portion: 0.5 autoPresented: true timeSpent: 40.5 timestamp: 1348151906 - itemId: item-x userId: user-b sessionId: null portion: 1 autoPresented: false timeSpent: 0 timestamp: 1348239363 '400': description: The `itemId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/users/{userId}/viewportions/: get: summary: List User View Portions description: | Lists all the view portions ever submitted by the given user. tags: - User-Item Interactions parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user whose view portions are to be listed. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array items: $ref: '#/components/schemas/ViewPortion' examples: response: value: - itemId: item-x userId: user-a sessionId: ABAD1D portion: 0.25 autoPresented: false timeSpent: 1.5 timestamp: 1348151906 - itemId: item-y userId: user-a sessionId: EWQKOL portion: 0.1 autoPresented: true timeSpent: 231.25 timestamp: 1348239363 '400': description: The `userId` does not match ^[a-zA-Z0-9_\-:@\.]+$. '404': description: >- 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. /{databaseId}/recomms/users/{userId}/items/: post: summary: Recommend Items to User description: > Based on the user's past interactions (purchases, ratings, etc.) with the items, recommends top-N items that are most likely to be of high value for the given user. The most typical use cases are recommendations on the homepage, in some "Picked just for you" section, or in email. The returned items are sorted by relevance (the first item being the most relevant). Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics). - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items). It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user for whom personalized recommendations are to be generated. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemsToUserParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb recomms: - id: item-146 - id: item-462 - id: item-463 numberNextRecommsCalls: 0 '400': description: >- userId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/recomms/items/{itemId}/items/: post: summary: Recommend Items to Item description: > Recommends a set of items that are somehow related to one given item, *X*. A typical scenario is when the user *A* is viewing *X*. Then you may display items to the user that he might also be interested in. Recommend items to item request gives you Top-N such items, optionally taking the target user *A* into account. The returned items are sorted by relevance (the first item being the most relevant). Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: - Let Recombee know that this recommendation was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics). - Get subsequent recommended items when the user scrolls down (*infinite scroll*) or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items). It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: ID of the item for which the recommendations are to be generated. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemsToItemParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 768448ea-10b3-4028-bb76-4b2f95121d19 recomms: - id: item-146 - id: item-462 - id: item-463 numberNextRecommsCalls: 0 '400': description: >- itemId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/recomms/item-segments/items/: post: summary: Recommend Items to Item Segment description: > Recommends Items that are the most relevant to a particular Segment from a context [Segmentation](https://docs.recombee.com/segmentations). Based on the used Segmentation, this endpoint can be used for example for: - Recommending articles related to a particular topic - Recommending songs belonging to a particular genre - Recommending products produced by a particular brand You need to set the used context Segmentation in the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned items are sorted by relevance (the first item being the most relevant). It is also possible to use the POST HTTP method (for example, in the case of a very long ReQL filter) — query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemsToItemSegmentParameters' description: Recommendation parameters definition required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 768448ea-10b3-4028-bb76-4b2f95121d19 recomms: - id: item-176 - id: item-141 - id: item-967 numberNextRecommsCalls: 0 '400': description: count is not a positive integer. '404': description: contextSegmentId not found in the context segmentation /{databaseId}/recomms/next/items/{recommId}: post: summary: Recommend Next Items description: > Returns items that shall be shown to a user as next recommendations when the user e.g. scrolls the page down (*infinite scroll*) or goes to the next page. It accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (`count`). The base request can be one of: - [Recommend Items to Item](https://docs.recombee.com/api#recommend-items-to-item) - [Recommend Items to User](https://docs.recombee.com/api#recommend-items-to-user) - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) - [Search Items](https://docs.recombee.com/api#search-items) All the other parameters are inherited from the base request. *Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items. The number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field. *Recommend next items* can be requested up to 30 minutes after the base request or a previous *Recommend next items* call. For billing purposes, each call to *Recommend next items* is counted as a separate recommendation request. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: recommId in: path description: ID of the base recommendation request for which next recommendations should be returned required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendNextItemsParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 768448ea-10b3-4028-bb76-4b2f95121d19 recomms: - id: item-176 - id: item-141 - id: item-967 numberNextRecommsCalls: 4 '400': description: Parameter `count` is not given or is not a positive integer. Parameter `recommId` is not an UUID. '404': description: Base request with the given `recommId` does not exist or has expired. /{databaseId}/recomms/users/{userId}/users/: post: summary: Recommend Users to User description: > 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). tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: User to whom we find similar users required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendUsersToUserParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: f88d970d-561c-460f-b4d4-faf0478244ca recomms: - id: user-64 - id: user-42 - id: user-23 numberNextRecommsCalls: 0 '400': description: >- userId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/recomms/items/{itemId}/users/: post: summary: Recommend Users to Item description: > 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). tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: ID of the item for which the recommendations are to be generated. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendUsersToItemParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: ee94fa8b-efe7-4b35-abc6-2bc3456d66ed recomms: - id: user-64 - id: user-42 - id: user-23 numberNextRecommsCalls: 0 '400': description: >- itemId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/recomms/users/{userId}/item-segments/: post: summary: Recommend Item Segments to User description: > Recommends the top Segments from a [Segmentation](https://docs.recombee.com/segmentations) for a particular user, based on the user's past interactions. Based on the used Segmentation, this endpoint can be used for example for: - Recommending the top categories for the user - Recommending the top genres for the user - Recommending the top brands for the user - Recommending the top artists for the user You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user for whom personalized recommendations are to be generated. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemSegmentsToUserParameters' description: Recommendation parameters definition required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 5fbd94fa-2553-422c-bdb5-af82687d8c6a recomms: - id: category-rap - id: category-dnb - id: category-electronic numberNextRecommsCalls: 0 '400': description: >- Used Segmentation not configured for the scenario. userId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer. '404': description: userId not found in the database and cascadeCreate is false /{databaseId}/recomms/items/{itemId}/item-segments/: post: summary: Recommend Item Segments to Item description: > Recommends Segments from a [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular item. Based on the used Segmentation, this endpoint can be used for example for: - Recommending the related categories - Recommending the related genres - Recommending the related brands - Recommending the related artists You need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: itemId in: path description: ID of the item for which the recommendations are to be generated. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemSegmentsToItemParameters' description: Recommendation parameters definition required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 5fbd94fa-2553-422c-bdb5-af82687d8c6a recomms: - id: category-rap - id: category-dnb - id: category-electronic numberNextRecommsCalls: 0 '400': description: >- Used Segmentation not configured for the scenario. itemId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer. '404': description: itemId not found in the database and cascadeCreate is false /{databaseId}/recomms/item-segments/item-segments/: post: summary: Recommend Item Segments to Item Segment description: > Recommends Segments from a result [Segmentation](https://docs.recombee.com/segmentations) that are the most relevant to a particular Segment from a context Segmentation. Based on the used Segmentations, this endpoint can be used for example for: - Recommending the related brands to particular brand - Recommending the related brands to particular category - Recommending the related artists to a particular genre (assuming songs are the Items) You need to set the used context and result Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint. The returned segments are sorted by relevance (first segment being the most relevant). It is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RecommendItemSegmentsToItemSegmentParameters' description: Recommendation parameters definition required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/RecommendationResponse' examples: response: value: recommId: 5fbd94fa-2553-422c-bdb5-af82687d8c6a recomms: - id: category-rap - id: category-dnb - id: category-electronic numberNextRecommsCalls: 0 '400': description: count is not a positive integer. '404': description: contextSegmentId not found in the context segmentation /{databaseId}/recomms/composite/: post: summary: Composite Recommendation description: > Composite Recommendation returns both a *source entity* (e.g., an Item or [Item Segment](https://docs.recombee.com/segmentations.html)) and a list of related recommendations in a single response. It is ideal for use cases such as personalized homepage sections (*Articles from *), *Because You Watched *, or *Artists Related to Your Favorite Artist *. See detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations). **Structure** The endpoint operates in two stages: 1. Recommends the *source* (e.g., an Item Segment or item) to the user. 2. Recommends *results* (items or Item Segments) related to that *source*. For example, *Articles from * can be decomposed into: - [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category. - [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category. Since the first step uses [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user), you must include the `userId` parameter in the *Composite Recommendation* request. Each *Composite Recommendation* counts as a single recommendation API request for billing. **Stage-specific Parameters** Additional parameters can be supplied via [sourceSettings](https://docs.recombee.com/api#composite-recommendation-param-sourceSettings) and [resultSettings](https://docs.recombee.com/api#composite-recommendation-param-resultSettings). In the example above: - `sourceSettings` may include any parameter valid for [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-items-to-user) (e.g., `filter`, `booster`). - `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment). See [this example](https://docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details. tags: - Recommendations parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CompositeRecommendationParameters' description: Recommendation parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/CompositeRecommendationResponse' examples: response: value: recommId: ee94fa8b-efe7-4b35-abc6-2bc3456d66ed source: id: category-4 recomms: - id: item-64 - id: item-42 - id: item-23 numberNextRecommsCalls: 0 '400': description: Count is not a positive integer, provided scenario not found. '404': description: >- 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. /{databaseId}/search/users/{userId}/items/: post: summary: Search Items description: > Full-text personalized search. The results are based on the provided `searchQuery` and also on the user's past interactions (purchases, ratings, etc.) with the items (items more suitable for the user are preferred in the results). All the string and set item properties are indexed by the search engine. This endpoint should be used in a search box on your website/app. It can be called multiple times as the user is typing the query in order to get the most viable suggestions based on the current state of the query, or once after submitting the whole query. The returned items are sorted by relevance (the first item being the most relevant). Besides the recommended items, also a unique `recommId` is returned in the response. It can be used to: - Let Recombee know that this search was successful (e.g., user clicked one of the recommended items). See [Reported metrics](https://docs.recombee.com/admin_ui#reported-metrics). - Get subsequent search results when the user scrolls down or goes to the next page. See [Recommend Next Items](https://docs.recombee.com/api#recommend-next-items). It is also possible to use POST HTTP method (for example in the case of a very long ReQL filter) - query parameters then become body parameters. tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user for whom personalized search will be performed. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchItemsParameters' description: Search parameters definition required: true responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: response: value: recommId: 4fd901fe-4ba1-a3f1-a690-f4f01f76d4eb recomms: - id: item-476 - id: item-412 - id: item-773 numberNextRecommsCalls: 0 '400': description: >- userId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, searchQuery is not provided, filter or booster are not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/search/users/{userId}/item-segments/: post: summary: Search Item Segments description: > 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. tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: userId in: path description: ID of the user for whom personalized search will be performed. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchItemSegmentsParameters' description: Search parameters definition required: true responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/SearchResponse' examples: response: value: recommId: 7acdc8b5-f731-44f8-b522-72625044666f recomms: - id: cell phones - id: cell phone accessories numberNextRecommsCalls: 0 '400': description: >- userId does not match ^[a-zA-Z0-9_\-:@\.]+$, count is not a positive integer, searchQuery is not provided, filter or booster is not valid [ReQL](https://docs.recombee.com/reql) expressions, filter expression does not return boolean, booster does not return double or integer. '404': description: >- 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. /{databaseId}/synonyms/items/: post: summary: Add Search Synonym description: | Adds a new synonym for the [Search items](https://docs.recombee.com/api#search-items). When the `term` is used in the search query, the `synonym` is also used for the full-text search. Unless `oneWay=true`, it works also in the opposite way (`synonym` -> `term`). An example of a synonym can be `science fiction` for the term `sci-fi`. tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/SearchSynonymParams' description: Search synonym description required: true responses: '201': description: Successful operation. Returns data about the added synonym (including `id`). content: application/json: schema: $ref: '#/components/schemas/SearchSynonym' examples: response: value: id: cc198c86-e015-bb74-b5f4-8f996fd26736 term: sci-fi synonym: science fiction oneWay: false '400': description: Missing a field, or a field has a wrong type. '409': description: >- `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: summary: List Search Synonyms description: Gives the list of synonyms defined in the database. tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: count in: query description: The number of synonyms to be listed. required: false schema: type: integer - name: offset in: query description: Specifies the number of synonyms to skip (ordered by `term`). required: false schema: type: integer responses: '200': description: Successful operation. content: application/json: schema: $ref: '#/components/schemas/ListSearchSynonymsResponse' examples: response: value: 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: summary: Delete All Search Synonyms description: | Deletes all synonyms defined in the database. tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. /{databaseId}/synonyms/items/{id}: delete: summary: Delete Search Synonym description: > Deletes synonym of the given `id`. This synonym is no longer taken into account in the [Search items](https://docs.recombee.com/api#search-items). tags: - Search parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: id in: path description: ID of the synonym that should be deleted. required: true schema: type: string responses: '200': description: Successful operation. '404': description: Synonym with the given `id` does not exist. /{databaseId}/segmentations/property-based/{segmentationId}: put: summary: Create Property Based Segmentation description: | 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. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the newly created Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreatePropertyBasedSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$, property is not of supported type (`string` or `set`). '404': description: Property does not exist. post: summary: Update Property Based Segmentation description: | Updates a Property Based Segmentation tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the updated Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdatePropertyBasedSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$, property is not of supported type (`string` or `set`). '404': description: Property does not exist. Segmentation with given ID does not exist. /{databaseId}/segmentations/auto-reql/{segmentationId}: put: summary: Create Auto ReQL Segmentation description: | Segment the items using a [ReQL](https://docs.recombee.com/reql) expression. For each item, the expression should return a set that contains IDs of segments to which the item belongs to. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the newly created Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAutoReQLSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$, ReQL expression is invalid. post: summary: Update Auto ReQL Segmentation description: | Update an existing Segmentation. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the updated Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateAutoReQLSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: >- segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$. ReQL expression is invalid. Given Segmentation is of different type. '404': description: Segmentation with given ID does not exist. /{databaseId}/segmentations/manual-reql/{segmentationId}: put: summary: Create Manual ReQL Segmentation description: | Segment the items using multiple [ReQL](https://docs.recombee.com/reql) filters. Use the Add Manual ReQL Items Segment endpoint to create the individual segments. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the newly created Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateManualReQLSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$. post: summary: Update Manual ReQL Segmentation description: | Update an existing Segmentation. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the updated Segmentation required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/UpdateManualReQLSegmentationParameters' description: Segmentation parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId does not match ^[a-zA-Z0-9_\-:@\.]+$. Given Segmentation is of different type. '404': description: Segmentation with given ID does not exist. /{databaseId}/segmentations/manual-reql/{segmentationId}/segments/{segmentId}: put: summary: Add Manual ReQL Segment description: > Adds a new Segment into a Manual ReQL Segmentation. The new Segment is defined by a [ReQL](https://docs.recombee.com/reql) filter that returns `true` for an item in case that this item belongs to the segment. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the Segmentation to which the new Segment should be added required: true schema: type: string - name: segmentId in: path description: ID of the newly created Segment required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManualReQLSegmentParameters' description: Add Segment parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId or segmentId does not match ^[a-zA-Z0-9_\-:@\.]+$. Segmentation is of wrong type. '404': description: Segmentation with given ID does not exist. post: summary: Update Manual ReQL Segment description: | Update definition of the Segment. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the Segmentation to which the updated Segment belongs required: true schema: type: string - name: segmentId in: path description: ID of the Segment that will be updated required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ManualReQLSegmentParameters' description: Update Segment parameters definition required: true responses: '201': description: successful operation '400': description: segmentationId or segmentId does not match ^[a-zA-Z0-9_\-:@\.]+$. Segmentation is of wrong type. '404': description: Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation. delete: summary: Delete Manual ReQL Segment description: | Delete a Segment from a Manual ReQL Segmentation. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the Segmentation from which the Segment should be deleted required: true schema: type: string - name: segmentId in: path description: ID of the Segment that should be deleted required: true schema: type: string responses: '201': description: successful operation '400': description: segmentationId or segmentId does not match ^[a-zA-Z0-9_\-:@\.]+$. Segmentation is of wrong type. '404': description: Segmentation with given ID does not exist. Segment with given ID does not exist in the Segmentation. /{databaseId}/segmentations/list/: get: summary: List Segmentations description: | Return all existing items Segmentations. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: sourceType in: query description: List Segmentations based on a particular type of data. Currently only `items` are supported. required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/ListSegmentationsResponse' examples: response: value: 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 /{databaseId}/segmentations/list/{segmentationId}: get: summary: Get Segmentation description: | Get existing Segmentation. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the Segmentation that should be returned required: true schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/Segmentation' examples: response: value: segmentationId: category sourceType: items segmentationType: property title: Category Segmentation description: Groups items by their category '404': description: Segmentation with given ID does not exist. /{databaseId}/segmentations/{segmentationId}: delete: summary: Delete Segmentation description: | Delete existing Segmentation. tags: - Segmentations Definition parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string - name: segmentationId in: path description: ID of the Segmentation that should be deleted required: true schema: type: string responses: '200': description: successful operation '404': description: Segmentation with given ID does not exist. /{databaseId}/batch/: post: summary: Batch description: > 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). tags: - Miscellaneous parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/Batch' description: Batch required: true responses: '200': description: >- Successful operation. There is an array with responses. The order of the responses in the array follows the order of the sent requests. content: application/json: examples: response: value: - code: 200 json: ok - code: 200 json: ok - code: 200 json: recommId: 3f6ad2f2-a3f1-4ba1-a690-f4f01f76d4eb recomms: - id: item-146 - id: item-462 - id: item-463 numberNextRecommsCalls: 0 '400': description: > Many possibilities, see the error description in the result JSON. Examples: invalid or missing Content-type (not `application/json`), request body is not a valid JSON, request JSON does not have the prescribed structure. '404': description: >- There is at least one request in the batch with an invalid (non-existing) URL. In such a case, the batch as a whole **is not executed** and you'll get HTTP 404, because the batch is apriori erroneous. '413': description: Too large batch (containing more than 10,000 requests in case of a server side request). /{databaseId}/scenarios/: get: summary: List Scenarios description: | Get all [Scenarios](https://docs.recombee.com/scenarios) of the given database. tags: - Miscellaneous parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. content: application/json: schema: type: array description: Array of existing Scenarios items: $ref: '#/components/schemas/Scenario' examples: response: value: - id: relatedArticles endpoint: recommendItemsToItem - id: justForYou endpoint: recommendItemsToUser - id: homepageSectionsOrdering endpoint: recommendItemSegmentsToUser - id: homepageSectionContent endpoint: recommendItemsToItemSegment /{databaseId}/: delete: summary: Reset Database description: > 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. tags: - Miscellaneous parameters: - name: databaseId in: path description: ID of your database. required: true schema: type: string responses: '200': description: Successful operation. servers: - url: http://Based on the region of your database (see https://docs.recombee.com/regions). - url: https://Based on the region of your database (see https://docs.recombee.com/regions). components: schemas: PropertyInfo: type: object required: - name - type properties: name: type: string description: Name of the property type: type: string description: Type of the property SeriesItem: type: object required: - itemType - itemId - time properties: itemType: type: string description: '`item` iff the regular item from the catalog is to be inserted, `series` iff series is inserted as the item.' itemId: type: string description: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. time: type: number format: double description: >- Time index used for sorting items in the series. According to time, items are sorted within series in ascending order. In the example of TV show episodes, the episode number is a natural choice to be passed as time. cascadeCreate: type: boolean description: >- 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. RemoveSeriesItem: type: object required: - itemType - itemId properties: itemType: type: string description: Type of the item to be removed. itemId: type: string description: ID of the item iff `itemType` is `item`. ID of the series iff `itemType` is `series`. AddSeries: type: object properties: cascadeCreate: type: boolean description: If set to `true`, the item will be created with the same ID as the series. Default is `true`. DeleteSeries: type: object properties: cascadeDelete: type: boolean description: If set to `true`, item with the same ID as seriesId will be also deleted. Default is `false`. DetailView: type: object required: - userId - itemId properties: userId: type: string description: User who viewed the item itemId: type: string description: Viewed item timestamp: format: double description: UTC timestamp of the view as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number duration: type: integer description: Duration of the view cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. recommId: type: string description: >- If this detail view is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. autoPresented: type: boolean description: >- 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`. Purchase: type: object required: - userId - itemId properties: userId: type: string description: User who purchased the item itemId: type: string description: Purchased item timestamp: format: double description: UTC timestamp of the purchase as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. amount: type: number format: double description: >- Amount (number) of purchased items. The default is 1. For example, if `user-x` purchases two `item-y` during a single order (session...), the `amount` should equal 2. price: type: number format: double description: >- Price paid by the user for the item. If `amount` is greater than 1, the sum of prices of all the items should be given. profit: type: number format: double description: >- Your profit from the purchased item. The profit is natural in the e-commerce domain (for example, if `user-x` purchases `item-y` for $100 and the gross margin is 30 %, then the profit is $30) but is also applicable in other domains (for example, at a news company it may be income from a displayed advertisement on article page). If `amount` is greater than 1, the sum of profit of all the items should be given. recommId: type: string description: If this purchase is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. Rating: type: object required: - userId - itemId - rating properties: userId: type: string description: User who submitted the rating itemId: type: string description: Rated item timestamp: format: double description: UTC timestamp of the rating as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number rating: type: number format: double description: >- Rating rescaled to interval [-1.0,1.0], where -1.0 means the worst rating possible, 0.0 means neutral, and 1.0 means absolutely positive rating. For example, in the case of 5-star evaluations, rating = (numStars-3)/2 formula may be used for the conversion. cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. recommId: type: string description: If this rating is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. CartAddition: type: object required: - userId - itemId properties: userId: type: string description: User who added the item to the cart itemId: type: string description: Item added to the cart timestamp: format: double description: >- UTC timestamp of the cart addition as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. amount: type: number format: double description: >- Amount (number) added to cart. The default is 1. For example, if `user-x` adds two `item-y` during a single order (session...), the `amount` should equal 2. price: type: number format: double description: Price of the added item. If `amount` is greater than 1, the sum of prices of all the items should be given. recommId: type: string description: >- If this cart addition is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. Bookmark: type: object required: - userId - itemId properties: userId: type: string description: User who bookmarked the item itemId: type: string description: Bookmarked item timestamp: format: double description: UTC timestamp of the bookmark as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. recommId: type: string description: If this bookmark is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. ViewPortion: type: object required: - userId - itemId - portion properties: userId: type: string description: User who viewed a portion of the item itemId: type: string description: Viewed item portion: type: number format: double description: >- Viewed portion of the item (number between 0.0 (viewed nothing) and 1.0 (viewed full item) ). It should be the actual viewed part of the item, no matter the seeking. For example, if the user seeked immediately to half of the item and then viewed 10% of the item, the `portion` should still be `0.1`. sessionId: type: string description: >- ID of the session in which the user viewed the item. Default is `null` (`None`, `nil`, `NULL` etc., depending on the language). timestamp: format: double description: >- UTC timestamp of the view portion as ISO8601-1 pattern or UTC epoch time. The default value is the current time. oneOf: - type: string - type: number cascadeCreate: type: boolean description: Sets whether the given user/item should be created if not present in the database. recommId: type: string description: >- If this view portion is based on a recommendation request, `recommId` is the id of the clicked recommendation. additionalData: type: object description: A dictionary of additional data for the interaction. autoPresented: type: boolean description: >- Indicates whether the item was automatically presented to the user (e.g., in a swiping feed) or explicitly requested by the user (e.g., by clicking on a link). Defaults to `false`. timeSpent: type: number format: double description: >- 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. UpdateMoreItemsParameters: type: object required: - filter - changes properties: filter: description: >- A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated. type: string changes: type: object description: A dictionary where the keys are properties that shall be updated. UpdateMoreItemsResponse: type: object required: - count - itemIds properties: count: type: integer description: Number of updated items itemIds: description: IDs of updated items type: array items: type: string DeleteMoreItemsParameters: type: object required: - filter properties: filter: description: >- A [ReQL](https://docs.recombee.com/reql) expression, which returns `true` for the items that shall be updated. type: string DeleteMoreItemsResponse: type: object required: - count - itemIds properties: count: type: integer description: Number of deleted items itemIds: description: IDs of deleted items type: array items: type: string RecommendItemsToUserParameters: type: object required: - count properties: count: description: | Number of items to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: > 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. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "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 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string diversity: description: > **Expert option:** Real number from [0.0, 1.0], which determines how mutually dissimilar the recommended items should be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. type: number format: double minRelevance: description: > **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. enum: - low - medium - high type: string rotationRate: description: > **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`. type: number format: double rotationTime: description: > **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`. type: number format: double expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean RecommendUsersToUserParameters: type: object required: - count properties: count: description: Number of users to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: >- 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. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "recommId": "b326d82d-5d57-4b45-b362-c9d6f0895855", "recomms": [ { "id": "user-17", "values": { "country": "US" } }, { "id": "user-2", "values": { "country": "CAN" } } ], "numberNextRecommsCalls": 0 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string diversity: description: > **Expert option:** Real number from [0.0, 1.0], which determines how mutually dissimilar the recommended users should be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. type: number format: double minRelevance: description: > **Expert option:** Specifies the threshold of how relevant must the recommended users be. Possible values one of: "low", "medium", "high". enum: - low - medium - high type: string rotationRate: description: > **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. type: number format: double rotationTime: description: > **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. type: number format: double expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean RecommendItemsToItemParameters: type: object required: - targetUserId - count properties: targetUserId: description: | 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. type: string count: description: Number of items to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: >- 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. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "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 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])", "isFromSameCompany": "'company' == context_item[\"company\"]" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string userImpact: description: > **Expert option:** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get a user-based recommendation. The default value is `0`. type: number format: double diversity: description: > **Expert option:** Real number from [0.0, 1.0], which determines how mutually dissimilar the recommended items should be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. type: number format: double minRelevance: description: > **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. enum: - low - medium - high type: string rotationRate: description: > **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. type: number format: double rotationTime: description: > **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. type: number format: double expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean RecommendUsersToItemParameters: type: object required: - count properties: count: description: Number of users to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: If an item of the given *itemId* doesn't exist in the database, it creates the missing item. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "recommId": "b2b355dd-972a-4728-9c6b-2dc229db0678", "recomms": [ { "id": "user-17", "values": { "country": "US" } }, { "id": "user-2", "values": { "country": "CAN" } } ], "numberNextRecommsCalls": 0 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended users based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some users based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended user. This can be used to compute additional properties of the recommended users that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])", "isFromSameCompany": "'company' == context_item[\"company\"]" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string diversity: description: > **Expert option:** Real number from [0.0, 1.0], which determines how mutually dissimilar the recommended users should be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. type: number format: double expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean RecommendItemSegmentsToUserParameters: type: object required: - count properties: count: description: | Number of item segments to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: > 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. type: boolean filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. type: string logic: $ref: '#/components/schemas/Logic' expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ```json { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` type: object additionalProperties: type: string RecommendItemSegmentsToItemParameters: type: object required: - targetUserId - count properties: targetUserId: description: | 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. type: string count: description: | Number of item segments to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: > 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. type: boolean filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. type: string logic: $ref: '#/components/schemas/Logic' expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ```json { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` type: object additionalProperties: type: string RecommendItemSegmentsToItemSegmentParameters: type: object required: - contextSegmentId - targetUserId - count properties: contextSegmentId: type: string description: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. targetUserId: description: | 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. type: string count: description: | Number of item segments to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: > 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. type: boolean filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. type: string logic: $ref: '#/components/schemas/Logic' expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ```json { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` type: object additionalProperties: type: string RecommendItemsToItemSegmentParameters: type: object required: - contextSegmentId - targetUserId - count properties: contextSegmentId: type: string description: ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. targetUserId: description: | 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. type: string count: description: Number of items to be recommended (N for the top-N recommendation). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: >- 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. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "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 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string minRelevance: description: > **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. enum: - low - medium - high type: string rotationRate: description: > **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. type: number format: double rotationTime: description: > **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. type: number format: double expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean CompositeRecommendationStageParameters: type: object required: [] properties: returnProperties: description: > 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 with `returnProperties` set in the `resultSettings`: ```json { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "categories": ["Sport", "Football"], "author": "Jane Smith", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "categories": ["Sport", "Olympics"], "author": "Mark Johnson", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "categories": ["Sport", "Tennis"], "author": "Laura Chen", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` type: boolean includedProperties: description: > Allows specifying which properties should be returned when `returnProperties=true` is set. The properties are given as a comma-separated list. Example response for `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`: ```json { "recommId": "ee94fa8b-efe7-4b35-abc6-2bc3456d66ed", "source": { "id": "category-sport" }, "recomms": [ { "id": "article-1024", "values": { "title": "Champions League: Stunning Comeback Secures Final Spot", "url": "newsportal.com/articles/champions-league-comeback" } }, { "id": "article-2031", "values": { "title": "Top 10 Moments from the Summer Olympics", "url": "newsportal.com/articles/olympic-top-moments" } }, { "id": "article-3042", "values": { "title": "Rising Stars in Women's Tennis to Watch This Season", "url": "newsportal.com/articles/womens-tennis-stars" } } ], "numberNextRecommsCalls": 0 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended entities based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some entities based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > Only usable if the stage corresponds to the one of these recommendation endpoints: - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user) - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item) - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) - [Recommend Users to Item](https://docs.recombee.com/api#recommend-users-to-item) - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user) A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ```json { "recommId": "ce52ada4-e4d9-4885-943c-407db2dee837", "source": { "id": "restaurant-123", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 3450.5 } }, "recomms": [ { "id": "restaurant-178", "reqlEvaluations": { "isInUsersCity": true, "distanceToUser": 5200.2 } }, { "id": "bar-42", "reqlEvaluations": { "isInUsersCity": false, "distanceToUser": 2516.0 } } ], "numberNextRecommsCalls": 0 } ``` type: object additionalProperties: type: string minRelevance: description: > **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user) - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item) - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) If the *userId* 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. enum: - low - medium - high type: string rotationRate: description: > **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user) - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item) - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user) If the *userId* 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. type: number format: double rotationTime: description: > **Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints: - [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user) - [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item) - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) - [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user) If the *userId* 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. type: number format: double CompositeRecommendationParameters: type: object required: - count - scenario properties: scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string count: description: | Number of items to be recommended (N for the top-N recommendation). type: integer itemId: description: | ID of the item for which the recommendations are to be generated. type: string userId: description: | ID of the user for which the recommendations are to be generated. type: string logic: $ref: '#/components/schemas/Logic' segmentId: description: | ID of the segment from `contextSegmentationId` for which the recommendations are to be generated. type: string cascadeCreate: description: > 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. type: boolean sourceSettings: description: > Parameters applied for recommending the *Source* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Source*. type: object schema: $ref: '#/components/schemas/CompositeRecommendationStageParameters' resultSettings: description: > Parameters applied for recommending the *Result* stage. The accepted parameters correspond with the recommendation sub-endpoint used to recommend the *Result*. type: object schema: $ref: '#/components/schemas/CompositeRecommendationStageParameters' expertSettings: description: | Dictionary of custom options. type: object SearchItemsParameters: type: object required: - count - searchQuery properties: searchQuery: description: Search query provided by the user. It is used for the full-text search. type: string count: description: Number of items to be returned (N for the top-N results). type: integer scenario: description: > Scenario defines a particular search field in your user interface. You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each field performs. The AI that optimizes models to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. type: string cascadeCreate: description: >- 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. type: boolean returnProperties: description: > 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: ```json { "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 } ``` type: boolean includedProperties: description: > 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`: ```json { "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 } ``` type: array items: type: string filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to filter recommended items based on the values of their attributes. Filters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression, which allows you to boost the recommendation rate of some items based on the values of their attributes. Boosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). type: string logic: $ref: '#/components/schemas/Logic' reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item. This can be used to compute additional properties of the recommended items that are not stored in the database. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "isInUsersCity": "context_user[\"city\"] in 'cities'", "distanceToUser": "earth_distance('location', context_user[\"location\"])" } } ``` Example response: ```json { "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 } ``` type: object additionalProperties: type: string expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean SearchItemSegmentsParameters: type: object required: - count - searchQuery properties: searchQuery: description: Search query provided by the user. It is used for the full-text search. type: string count: description: Number of segments to be returned (N for the top-N results). type: integer scenario: description: > Scenario defines a particular application of recommendations. It can be, for example, "homepage", "cart", or "emailing". You can set various settings to the [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com). You can also see the performance of each scenario in the Admin UI separately, so you can check how well each application performs. The AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios. type: string cascadeCreate: description: > 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. type: boolean filter: description: > Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`. type: string booster: description: > Number-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to boost recommendation rate of some segments based on the `segmentationId`. type: string logic: $ref: '#/components/schemas/Logic' expertSettings: description: | Dictionary of custom options. type: object returnAbGroup: description: | If there is a custom AB-testing running, return the name of the group to which the request belongs. type: boolean reqlExpressions: description: > A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment. This can be used to compute additional properties of the recommended Item Segments. The keys are the names of the expressions, and the values are the actual ReQL expressions. Example request: ```json { "reqlExpressions": { "countItems": "size(segment_items(\"categories\", 'segmentId'))" } } ``` Example response: ```json { "recommId": "a7ac55a4-8d6e-4f19-addc-abac4164d8a8", "recomms": [ { "id": "category-fantasy-books", "reqlEvaluations": { "countItems": 486 } }, { "id": "category-sci-fi-costumes", "reqlEvaluations": { "countItems": 19 } } ], "numberNextRecommsCalls": 0 } ``` type: object additionalProperties: type: string RecommendNextItemsParameters: type: object required: - count properties: count: description: | Number of items to be recommended type: integer CreatePropertyBasedSegmentationParameters: type: object required: - sourceType - propertyName properties: sourceType: description: | What type of data should be segmented. Currently only `items` are supported. type: string propertyName: description: | Name of the property on which the Segmentation should be based type: string title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string UpdatePropertyBasedSegmentationParameters: type: object properties: propertyName: description: | Name of the property on which the Segmentation should be based type: string title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string CreateAutoReQLSegmentationParameters: type: object required: - sourceType - expression properties: sourceType: description: | What type of data should be segmented. Currently only `items` are supported. type: string expression: description: | ReQL expression that returns for each item a set with IDs of segments to which the item belongs type: string title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string UpdateAutoReQLSegmentationParameters: type: object properties: expression: description: | ReQL expression that returns for each item a set with IDs of segments to which the item belongs type: string title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string CreateManualReQLSegmentationParameters: type: object required: - sourceType properties: sourceType: description: | What type of data should be segmented. Currently only `items` are supported. type: string title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string UpdateManualReQLSegmentationParameters: type: object properties: title: description: | Human-readable name that is shown in the Recombee Admin UI. type: string description: description: | Description that is shown in the Recombee Admin UI. type: string ManualReQLSegmentParameters: type: object required: - filter properties: filter: description: | ReQL filter that returns `true` for items that belong to this Segment. Otherwise returns `false`. type: string title: description: | Human-readable name of the Segment that is shown in the Recombee Admin UI. type: string SearchResponse: type: object required: - recommId - recomms properties: recommId: type: string description: Id of the personalized search request recomms: type: array description: Results of the personalized search items: $ref: '#/components/schemas/Recommendation' numberNextRecommsCalls: type: integer description: How many times *Recommend Next Items* have been called for this `recommId` abGroup: type: string description: Name of AB-testing group to which the request belongs if there is a custom AB-testing running. RecommendationResponse: type: object required: - recommId - recomms properties: recommId: type: string description: Id of the recommendation request recomms: type: array description: Obtained recommendations items: $ref: '#/components/schemas/Recommendation' numberNextRecommsCalls: type: integer description: How many times *Recommend Next Items* have been called for this `recommId` abGroup: type: string description: Name of AB-testing group to which the request belongs if there is a custom AB-testing running. CompositeRecommendationResponse: type: object required: - recommId - source - recomms properties: recommId: type: string description: Id of the composite recommendation request source: $ref: '#/components/schemas/Recommendation' recomms: type: array description: Obtained recommendations items: $ref: '#/components/schemas/Recommendation' numberNextRecommsCalls: type: integer description: How many times *Recommend Next Items* have been called for this `recommId` Recommendation: type: object required: - id properties: id: type: string description: Id of the recommended item values: type: object description: Property values of the recommended item reqlEvaluations: type: object description: | Dictionary of evaluated ReQL expressions specified in the request and calculated for the recommended item. The keys are the names of the ReQL expressions, and the values are the results of the evaluations. Logic: properties: name: type: string description: Name of the logic that should be used settings: type: object description: Parameters passed to the logic oneOf: - type: string - type: object Batch: type: object required: - requests properties: requests: type: array items: type: object description: JSON array containing the requests. distinctRecomms: type: boolean description: >- Makes all the recommended items for a certain user distinct among multiple recommendation requests in the batch. Item: type: object required: - itemId properties: itemId: type: string description: Id of the item values: type: object description: Property values of the item User: type: object required: - userId properties: userId: type: string description: Id of the user values: type: object description: Property values of the user Series: type: object required: - seriesId properties: seriesId: type: string description: Id of the series Group: type: object required: - groupId properties: groupId: type: string description: Id of the group SearchSynonymParams: type: object required: - term - synonym properties: term: type: string description: A word to which the `synonym` is specified. synonym: type: string description: A word that should be considered equal to the `term` by the full-text search engine. oneWay: type: boolean description: | If set to `true`, only `term` -> `synonym` is considered. If set to `false`, also `synonym` -> `term` works. Default: `false`. SearchSynonym: type: object required: - id - term - synonym - oneWay properties: id: type: string description: Id of the synonym record term: type: string description: A word to which the `synonym` is specified. synonym: type: string description: A word that should be considered equal to `term` by the full-text search engine. oneWay: type: boolean description: | If set to `true`, only `term` -> `synonym` is considered. I set to `false`, also `synonym` -> `term` works. ListSearchSynonymsResponse: type: object required: - synonyms properties: synonyms: description: List of synonyms type: array items: $ref: '#/components/schemas/SearchSynonym' Scenario: type: object required: - id - endpoint properties: id: type: string description: ID of the Scenario endpoint: type: string description: Scenario endpoint defined in the Admin UI Segmentation: type: object required: - segmentationId - sourceType - segmentationType properties: segmentationId: type: string description: Id of the Segmentation sourceType: type: string description: Determines on which type of data (e.g. `items`) the Segmentation is based segmentationType: type: string description: Determines the type of the segmentation (Property-based, Manual ReQL, Auto ReQL) title: type: string description: Title of the Segmentation description: type: string description: Description of the Segmentation ListSegmentationsResponse: type: object required: - segmentations properties: segmentations: type: array description: Array of existing Segmentations items: $ref: '#/components/schemas/Segmentation'