{ "openapi": "3.0.0", "info": { "title": "Recombee API", "description": "This is the documentation for Recombee Recommendation API (https://docs.recombee.com/api)\n \nAuthentication 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.\n", "version": "4.1.0" }, "paths": { "/{databaseId}/items/{itemId}": { "put": { "summary": "Add Item", "description": "Adds new item of the given `itemId` to the items catalog.\n\nAll the item properties for the newly created items are set to null.\n", "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.\n\nIf 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.\n\nIf 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.\n", "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).\n", "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.\n", "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.\n\nExample of the body:\n```json\n {\n \"product_description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price_usd\": 342,\n \"in_stock_from\": \"2016-11-16T08:00Z\",\n \"image\": \"http://myexamplesite.com/products/4ktelevision3d/image.jpg\",\n \"other_images\": [\"http://myexamplesite.com/products/4ktelevision3d/image2.jpg\",\n \"http://myexamplesite.com/products/4ktelevision3d/image3.jpg\"]\n }\n```\nSet item values can also **cascade create** the item if it's not already present in the database.\n\nFor this functionality:\n\n* *When using the client libraries*:\n Set the optional *cascadeCreate* parameter to true, just like when creating an interaction.\n\n* *When using directly REST API*: Set special \"property\" `!cascadeCreate`.\n\n Example:\n ```json\n {\n \"product_description\": \"4K TV with 3D feature\",\n \"!cascadeCreate\": true\n }\n ```\n\n Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.\n", "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.\n" }, "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.\n" } } }, "get": { "summary": "Get Item Values", "description": "Gets all the current property values of the given item.\n", "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.\n", "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.\n" } } } }, "/{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. \n\nExample response:\n```json\n [\n {\n \"itemId\": \"tv-178\",\n \"description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price\": 342,\n \"url\": \"myshop.com/tv-178\"\n },\n {\n \"itemId\": \"mixer-42\",\n \"description\": \"Stainless Steel Mixer\",\n \"categories\": [\"Home & Kitchen\"],\n \"price\": 39,\n \"url\": \"myshop.com/mixer-42\"\n }\n ]\n```\n", "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.\n\nExample response for `includedProperties=description,price`:\n```json\n [\n {\n \"itemId\": \"tv-178\",\n \"description\": \"4K TV with 3D feature\",\n \"price\": 342\n },\n {\n \"itemId\": \"mixer-42\",\n \"description\": \"Stainless Steel Mixer\",\n \"price\": 39\n }\n ]\n```\n", "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.\n", "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.\n", "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`.\n\n* `int`- Signed integer number.\n\n* `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).\n\n* `string` - UTF-8 string.\n\n* `boolean` - *true* / *false*\n\n* `timestamp` - Value representing date and time.\n\n* `set` - Set of strings.\n\n* `image` - URL of an image (`jpeg`, `png` or `gif`).\n\n* `imageList` - List of URLs that refer to images. \n", "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.\n" }, "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.\n", "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.\n", "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.\n", "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.\n\nExample: *Setting all the items that are older than a week as unavailable*\n\n ```json\n {\n \"filter\": \"'releaseDate' < now() - 7*24*3600\",\n \"changes\": {\"available\": false}\n }\n ```\n", "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.\n", "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.\n" }, "404": { "description": "Property of the given name is not present in the database.\n" } } }, "delete": { "summary": "Delete More Items", "description": "Deletes all the items that pass the filter.\n\nIf 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:\n```json\n {\n \"filter\": \"'releaseDate' < now() - 7*24*3600\",\n }\n", "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.\n" } } } }, "/{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:\n```json\n {\n \"cascadeCreate\": true\n }\n```\n" }, "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.\n\nDeleting a series will only delete assignment of items to it, not the items themselves!\n", "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:\n```json\n {\n \"cascadeCreate\": true\n }\n```\n" }, "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.\n", "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\nExample of the body:\n```json\n {\n \"itemType\": \"series\",\n \"itemId\": \"season-1\",\n \"time\": 1\n }\n```\n", "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.\n" }, "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.\n" }, "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\nExample of the body:\n```json\n {\n \"itemType\": \"series\",\n \"itemId\": \"season-1\"\n }\n```\n", "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.\n", "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.\n\nIf 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.\n", "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).\n", "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.\n", "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.\n\nExample of the body:\n```json\n {\n \"country\": \"US\",\n \"sex\": \"F\"\n }\n```\nSet user values can also **cascade create** the user if it's not already present in the database.\n\nFor this functionality:\n\n* *When using the client libraries*:\n Set the optional *cascadeCreate* parameter to true, just like when creating an interaction.\n\n* *When using directly REST API*: Set special \"property\" `!cascadeCreate`.\n\n Example:\n ```json\n {\n \"country\": \"US\",\n \"!cascadeCreate\": true\n }\n ```\n\n Note the exclamation mark (!) at the beginning of the parameter's name to distinguish it from item property names.\n", "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.\n" }, "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.\n" } } }, "get": { "summary": "Get User Values", "description": "Gets all the current property values of the given user.\n", "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.\n", "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.\n" } } } }, "/{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.\n\n\nMerging 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**.\n\nBy default, the *Merge Users* request is only available from server-side integrations for security reasons, to prevent potential abuse.\nIf 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.\n", "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. \n\nExample response:\n```json\n [\n {\n \"userId\": \"user-81\",\n \"country\": \"US\",\n \"sex\": \"M\"\n },\n {\n \"userId\": \"user-314\",\n \"country\": \"CAN\",\n \"sex\": \"F\"\n }\n ]\n```\n", "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.\n\nExample response for `includedProperties=country`:\n```json\n [\n {\n \"userId\": \"user-81\",\n \"country\": \"US\"\n },\n {\n \"userId\": \"user-314\",\n \"country\": \"CAN\"\n }\n ]\n```\n", "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.\n", "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.\n", "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`.\n\n* `int` - Signed integer number.\n\n* `double` - Floating point number. It uses 64-bit base-2 format (IEEE 754 standard).\n\n* `string` - UTF-8 string.\n\n* `boolean` - *true* / *false*\n\n* `timestamp` - Value representing date and time.\n\n* `set` - Set of strings.\n", "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.\n" }, "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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).\nIf you send a new request with the same (`userId`, `itemId`, `sessionId`), the portion gets updated.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n\nThe most typical use cases are recommendations on the homepage, in some \"Picked just for you\" section, or in email.\n\nThe returned items are sorted by relevance (the first item being the most relevant).\n\nBesides the recommended items, also a unique `recommId` is returned in the response. It can be used to:\n\n- 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).\n- 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).\n\nIt 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.\n", "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.\n\nThe returned items are sorted by relevance (the first item being the most relevant).\n\nBesides the recommended items, also a unique `recommId` is returned in the response. It can be used to:\n\n- 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).\n- 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).\n\nIt 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.\n", "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).\n\nBased on the used Segmentation, this endpoint can be used for example for:\n\n- Recommending articles related to a particular topic\n- Recommending songs belonging to a particular genre\n- Recommending products produced by a particular brand\n\nYou 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.\n\nThe returned items are sorted by relevance (the first item being the most relevant).\n\nIt 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.\n", "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.\n\nIt accepts `recommId` of a base recommendation request (e.g., request from the first page) and the number of items that shall be returned (`count`).\nThe base request can be one of:\n - [Recommend Items to Item](https://docs.recombee.com/api#recommend-items-to-item)\n - [Recommend Items to User](https://docs.recombee.com/api#recommend-items-to-user)\n - [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)\n - [Search Items](https://docs.recombee.com/api#search-items)\n\nAll the other parameters are inherited from the base request.\n\n*Recommend next items* can be called many times for a single `recommId` and each call returns different (previously not recommended) items.\nThe number of *Recommend next items* calls performed so far is returned in the `numberNextRecommsCalls` field.\n\n*Recommend next items* can be requested up to 30 minutes after the base request or a previous *Recommend next items* call.\n\nFor billing purposes, each call to *Recommend next items* is counted as a separate recommendation request.\n", "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.\n\nIt 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.\n\nThe returned users are sorted by similarity (the first user being the most similar).\n", "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.\n\nIt 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.\n\nThe returned users are sorted by predicted interest in the item (the first user being the most interested).\n", "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.\n\nBased on the used Segmentation, this endpoint can be used for example for:\n\n - Recommending the top categories for the user\n - Recommending the top genres for the user\n - Recommending the top brands for the user\n - Recommending the top artists for the user\n\nYou need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.\n\nThe returned segments are sorted by relevance (first segment being the most relevant).\n\nIt is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.\n", "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.\n\nBased on the used Segmentation, this endpoint can be used for example for:\n\n - Recommending the related categories\n - Recommending the related genres\n - Recommending the related brands\n - Recommending the related artists\n\nYou need to set the used Segmentation the Admin UI in the [Scenario settings](https://docs.recombee.com/scenarios) prior to using this endpoint.\n\nThe returned segments are sorted by relevance (first segment being the most relevant).\n\nIt is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.\n", "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.\n\nBased on the used Segmentations, this endpoint can be used for example for:\n\n - Recommending the related brands to particular brand\n - Recommending the related brands to particular category\n - Recommending the related artists to a particular genre (assuming songs are the Items)\n\nYou 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.\n\nThe returned segments are sorted by relevance (first segment being the most relevant).\n\nIt is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.\n", "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.\n\nIt is ideal for use cases such as personalized homepage sections (*Articles from *), *Because You Watched *, or *Artists Related to Your Favorite Artist *.\n\nSee detailed **examples and configuration guidance** in the [Composite Scenarios documentation](https://docs.recombee.com/scenarios#composite-recommendations).\n\n**Structure**\n\nThe endpoint operates in two stages:\n1. Recommends the *source* (e.g., an Item Segment or item) to the user.\n2. Recommends *results* (items or Item Segments) related to that *source*.\n\nFor example, *Articles from * can be decomposed into:\n - [Recommend Item Segments To User](https://docs.recombee.com/api#recommend-item-segments-to-user) to find the category.\n - [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment) to recommend articles from that category.\n\nSince 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.\n\nEach *Composite Recommendation* counts as a single recommendation API request for billing.\n\n**Stage-specific Parameters**\n\nAdditional 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).\nIn the example above:\n - `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`).\n - `resultSettings` may include any parameter valid for [Recommend Items To Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment).\n\nSee [this example](https://docs.recombee.com/api#composite-recommendation-example-setting-parameters-for-individual-stages) for more details.\n", "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).\n\nAll the string and set item properties are indexed by the search engine.\n\nThis 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. \n\nThe returned items are sorted by relevance (the first item being the most relevant).\n\nBesides the recommended items, also a unique `recommId` is returned in the response. It can be used to:\n\n- 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).\n- 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).\n\nIt 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.\n", "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.).\n\nBased on the used Segmentation, this endpoint can be used for example for:\n\n - Searching within categories or brands\n - Searching within genres or artists\n\nFor example if the user is searching for \"iPhone\" this endpoint can return \"cell phones\" category.\n\nYou need to set the used Segmentation the Admin UI in the Scenario settings prior to using this endpoint.\n\nThe returned segments are sorted by relevance (first segment being the most relevant).\n\nIt is also possible to use POST HTTP method (for example in case of very long ReQL filter) - query parameters then become body parameters.\n", "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).\n\nWhen the `term` is used in the search query, the `synonym` is also used for the full-text search.\nUnless `oneWay=true`, it works also in the opposite way (`synonym` -> `term`).\n\nAn example of a synonym can be `science fiction` for the term `sci-fi`.\n", "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.\n", "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).\n", "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.\n\nA segment is created for each unique value of the property.\nIn case of `set` properties, a segment is created for each value in the set. Item belongs to all these segments.\n", "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\n", "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.\n\nFor each item, the expression should return a set that contains IDs of segments to which the item belongs to.\n", "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.\n", "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.\n\nUse the Add Manual ReQL Items Segment endpoint to create the individual segments.\n", "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.\n", "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.\n\nThe 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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n", "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.\n\nAny 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.\n\nUsing 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).\n", "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.\n" }, "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.\n", "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.\n", "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).\n", "type": "integer" }, "scenario": { "description": "Scenario defines a particular application of recommendations. It can be, for example, \"homepage\", \"cart\", or \"emailing\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price\": 342,\n \"url\": \"myshop.com/tv-178\"\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"categories\": [\"Home & Kitchen\"],\n \"price\": 39,\n \"url\": \"myshop.com/mixer-42\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=description,price`:\n```json\n {\n \"recommId\": \"a86ee8d5-cd8e-46d1-886c-8b3771d0520b\",\n \"recomms\":\n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"price\": 342\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"price\": 39\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended items that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n", "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.\n", "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`.\n", "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`.\n", "type": "number", "format": "double" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"9cb9c55d-50ba-4478-84fd-ab456136156e\",\n \"recomms\": \n [\n {\n \"id\": \"user-17\",\n \"values\": {\n \"country\": \"US\",\n \"sex\": \"F\"\n }\n },\n {\n \"id\": \"user-2\",\n \"values\": {\n \"country\": \"CAN\",\n \"sex\": \"M\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=country`:\n```json\n {\n \"recommId\": \"b326d82d-5d57-4b45-b362-c9d6f0895855\",\n \"recomms\":\n [\n {\n \"id\": \"user-17\",\n \"values\": {\n \"country\": \"US\"\n }\n },\n {\n \"id\": \"user-2\",\n \"values\": {\n \"country\": \"CAN\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended users that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n", "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\".\n", "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.\n", "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.\n", "type": "number", "format": "double" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" } } }, "RecommendItemsToItemParameters": { "type": "object", "required": [ "targetUserId", "count" ], "properties": { "targetUserId": { "description": "ID of the user who will see the recommendations.\n\nSpecifying the *targetUserId* is beneficial because:\n\n* It makes the recommendations personalized\n* Allows the calculation of Actions and Conversions\n in the graphical user interface,\n as Recombee can pair the user who got recommendations\n and who afterward viewed/purchased an item.\n\nIf you insist on not specifying the user, pass `null`\n(`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.\nDo not create some special dummy user for getting recommendations,\nas it could mislead the recommendation models,\nand result in wrong recommendations.\n\nFor anonymous/unregistered users, it is possible to use, for example, their session ID.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"0c6189e7-dc1a-429a-b613-192696309361\",\n \"recomms\":\n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price\": 342,\n \"url\": \"myshop.com/tv-178\"\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"categories\": [\"Home & Kitchen\"],\n \"price\": 39,\n \"url\": \"myshop.com/mixer-42\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=description,price`:\n```json\n {\n \"recommId\": \"6842c725-a79f-4537-a02c-f34d668a3f80\",\n \"recomms\": \n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"price\": 342\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"price\": 39\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended items that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\",\n \"isFromSameCompany\": \"'company' == context_item[\\\"company\\\"]\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2,\n \"isFromSameCompany\": false\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0,\n \"isFromSameCompany\": true\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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`.\n", "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.\n", "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.\n", "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.\n", "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.\n", "type": "number", "format": "double" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"039b71dc-b9cc-4645-a84f-62b841eecfce\",\n \"recomms\":\n [\n {\n \"id\": \"user-17\",\n \"values\": {\n \"country\": \"US\",\n \"sex\": \"F\"\n }\n },\n {\n \"id\": \"user-2\",\n \"values\": {\n \"country\": \"CAN\",\n \"sex\": \"M\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=country`:\n```json\n {\n \"recommId\": \"b2b355dd-972a-4728-9c6b-2dc229db0678\",\n \"recomms\":\n [\n {\n \"id\": \"user-17\",\n \"values\": {\n \"country\": \"US\"\n }\n },\n {\n \"id\": \"user-2\",\n \"values\": {\n \"country\": \"CAN\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended users that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\",\n \"isFromSameCompany\": \"'company' == context_item[\\\"company\\\"]\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2,\n \"isFromSameCompany\": false\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0,\n \"isFromSameCompany\": true\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n", "type": "number", "format": "double" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" } } }, "RecommendItemSegmentsToUserParameters": { "type": "object", "required": [ "count" ], "properties": { "count": { "description": "Number of item segments to be recommended (N for the top-N recommendation).\n", "type": "integer" }, "scenario": { "description": "Scenario defines a particular application of recommendations. It can be, for example, \"homepage\", \"cart\", or \"emailing\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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.\n", "type": "boolean" }, "filter": { "description": "Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.\n", "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`.\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" }, "reqlExpressions": { "description": "A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment.\nThis can be used to compute additional properties of the recommended Item Segments.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"countItems\": \"size(segment_items(\\\"categories\\\", 'segmentId'))\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"a7ac55a4-8d6e-4f19-addc-abac4164d8a8\",\n \"recomms\": \n [\n {\n \"id\": \"category-fantasy-books\",\n \"reqlEvaluations\": {\n \"countItems\": 486\n }\n },\n {\n \"id\": \"category-sci-fi-costumes\",\n \"reqlEvaluations\": {\n \"countItems\": 19\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "type": "object", "additionalProperties": { "type": "string" } } } }, "RecommendItemSegmentsToItemParameters": { "type": "object", "required": [ "targetUserId", "count" ], "properties": { "targetUserId": { "description": "ID of the user who will see the recommendations.\n\nSpecifying the *targetUserId* is beneficial because:\n\n* It makes the recommendations personalized\n* Allows the calculation of Actions and Conversions\n in the graphical user interface,\n as Recombee can pair the user who got recommendations\n and who afterward viewed/purchased an item.\n\nIf you insist on not specifying the user, pass `null`\n(`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.\nDo not create some special dummy user for getting recommendations,\nas it could mislead the recommendation models,\nand result in wrong recommendations.\n\nFor anonymous/unregistered users, it is possible to use, for example, their session ID.\n", "type": "string" }, "count": { "description": "Number of item segments to be recommended (N for the top-N recommendation).\n", "type": "integer" }, "scenario": { "description": "Scenario defines a particular application of recommendations. It can be, for example, \"homepage\", \"cart\", or \"emailing\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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.\n", "type": "boolean" }, "filter": { "description": "Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.\n", "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`.\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" }, "reqlExpressions": { "description": "A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment.\nThis can be used to compute additional properties of the recommended Item Segments.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"countItems\": \"size(segment_items(\\\"categories\\\", 'segmentId'))\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"a7ac55a4-8d6e-4f19-addc-abac4164d8a8\",\n \"recomms\": \n [\n {\n \"id\": \"category-fantasy-books\",\n \"reqlEvaluations\": {\n \"countItems\": 486\n }\n },\n {\n \"id\": \"category-sci-fi-costumes\",\n \"reqlEvaluations\": {\n \"countItems\": 19\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n\nSpecifying the *targetUserId* is beneficial because:\n\n* It makes the recommendations personalized\n* Allows the calculation of Actions and Conversions\n in the graphical user interface,\n as Recombee can pair the user who got recommendations\n and who afterward viewed/purchased an item.\n\nIf you insist on not specifying the user, pass `null`\n(`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.\nDo not create some special dummy user for getting recommendations,\nas it could mislead the recommendation models,\nand result in wrong recommendations.\n\nFor anonymous/unregistered users, it is possible to use, for example, their session ID.\n", "type": "string" }, "count": { "description": "Number of item segments to be recommended (N for the top-N recommendation).\n", "type": "integer" }, "scenario": { "description": "Scenario defines a particular application of recommendations. It can be, for example, \"homepage\", \"cart\", or \"emailing\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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.\n", "type": "boolean" }, "filter": { "description": "Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.\n", "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`.\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" }, "reqlExpressions": { "description": "A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment.\nThis can be used to compute additional properties of the recommended Item Segments.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"countItems\": \"size(segment_items(\\\"categories\\\", 'segmentId'))\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"a7ac55a4-8d6e-4f19-addc-abac4164d8a8\",\n \"recomms\": \n [\n {\n \"id\": \"category-fantasy-books\",\n \"reqlEvaluations\": {\n \"countItems\": 486\n }\n },\n {\n \"id\": \"category-sci-fi-costumes\",\n \"reqlEvaluations\": {\n \"countItems\": 19\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n\nSpecifying the *targetUserId* is beneficial because:\n\n* It makes the recommendations personalized\n* Allows the calculation of Actions and Conversions\n in the graphical user interface,\n as Recombee can pair the user who got recommendations\n and who afterward viewed/purchased an item.\n\nIf you insist on not specifying the user, pass `null`\n(`None`, `nil`, `NULL` etc., depending on the language) to *targetUserId*.\nDo not create some special dummy user for getting recommendations,\nas it could mislead the recommendation models,\nand result in wrong recommendations.\n\nFor anonymous/unregistered users, it is possible to use, for example, their session ID.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"0c6189e7-dc1a-429a-b613-192696309361\",\n \"recomms\":\n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price\": 342,\n \"url\": \"myshop.com/tv-178\"\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"categories\": [\"Home & Kitchen\"],\n \"price\": 39,\n \"url\": \"myshop.com/mixer-42\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=description,price`:\n```json\n {\n \"recommId\": \"6842c725-a79f-4537-a02c-f34d668a3f80\",\n \"recomms\": \n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"price\": 342\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"price\": 39\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended items that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "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.\n", "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.\n", "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.\n", "type": "number", "format": "double" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "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. \n\nExample response with `returnProperties` set in the `resultSettings`:\n```json\n {\n \"recommId\": \"ee94fa8b-efe7-4b35-abc6-2bc3456d66ed\",\n \"source\": {\n \"id\": \"category-sport\"\n },\n \"recomms\": [\n {\n \"id\": \"article-1024\",\n \"values\": {\n \"title\": \"Champions League: Stunning Comeback Secures Final Spot\",\n \"categories\": [\"Sport\", \"Football\"],\n \"author\": \"Jane Smith\",\n \"url\": \"newsportal.com/articles/champions-league-comeback\"\n }\n },\n {\n \"id\": \"article-2031\",\n \"values\": {\n \"title\": \"Top 10 Moments from the Summer Olympics\",\n \"categories\": [\"Sport\", \"Olympics\"],\n \"author\": \"Mark Johnson\",\n \"url\": \"newsportal.com/articles/olympic-top-moments\"\n }\n },\n {\n \"id\": \"article-3042\",\n \"values\": {\n \"title\": \"Rising Stars in Women's Tennis to Watch This Season\",\n \"categories\": [\"Sport\", \"Tennis\"],\n \"author\": \"Laura Chen\",\n \"url\": \"newsportal.com/articles/womens-tennis-stars\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n\n```\n", "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.\n\nExample response for `returnProperties=true` and `includedProperties=title,url` set in `resultSettings`:\n```json\n {\n \"recommId\": \"ee94fa8b-efe7-4b35-abc6-2bc3456d66ed\",\n \"source\": {\n \"id\": \"category-sport\"\n },\n \"recomms\": [\n {\n \"id\": \"article-1024\",\n \"values\": {\n \"title\": \"Champions League: Stunning Comeback Secures Final Spot\",\n \"url\": \"newsportal.com/articles/champions-league-comeback\"\n }\n },\n {\n \"id\": \"article-2031\",\n \"values\": {\n \"title\": \"Top 10 Moments from the Summer Olympics\",\n \"url\": \"newsportal.com/articles/olympic-top-moments\"\n }\n },\n {\n \"id\": \"article-3042\",\n \"values\": {\n \"title\": \"Rising Stars in Women's Tennis to Watch This Season\",\n \"url\": \"newsportal.com/articles/womens-tennis-stars\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "reqlExpressions": { "description": "Only usable if the stage corresponds to the one of these recommendation endpoints:\n\n- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)\n- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)\n- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)\n- [Recommend Users to Item](https://docs.recombee.com/api#recommend-users-to-item)\n- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)\n\nA dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended item.\nThis can be used to compute additional properties of the recommended items that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"source\": {\n \"id\": \"restaurant-123\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 3450.5\n }\n },\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "type": "object", "additionalProperties": { "type": "string" } }, "minRelevance": { "description": "**Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:\n\n- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)\n- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)\n- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)\n\nIf the *userId* is provided: Specifies the threshold of how relevant must the recommended items be to the user.\n\nPossible values one of: `\"low\"`, `\"medium\"`, `\"high\"`.\n\nThe 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*.\nThis 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.\n", "enum": [ "low", "medium", "high" ], "type": "string" }, "rotationRate": { "description": "**Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:\n- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)\n- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)\n- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)\n- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)\n\nIf 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.\n\nYou 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.\n", "type": "number", "format": "double" }, "rotationTime": { "description": "**Expert option:** Only usable if the stage corresponds to the one of these recommendation endpoints:\n- [Recommend Items To User](https://docs.recombee.com/api#recommend-items-to-user)\n- [Recommend Items To Item](https://docs.recombee.com/api#recommend-items-to-item)\n- [Recommend Items to Item Segment](https://docs.recombee.com/api#recommend-items-to-item-segment)\n- [Recommend Users To User](https://docs.recombee.com/api#recommend-users-to-user)\n\nIf 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.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "type": "string" }, "count": { "description": "Number of items to be recommended (N for the top-N recommendation).\n", "type": "integer" }, "itemId": { "description": "ID of the item for which the recommendations are to be generated.\n", "type": "string" }, "userId": { "description": "ID of the user for which the recommendations are to be generated.\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "segmentId": { "description": "ID of the segment from `contextSegmentationId` for which the recommendations are to be generated.\n", "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.\n", "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*.\n", "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*.\n", "type": "object", "schema": { "$ref": "#/components/schemas/CompositeRecommendationStageParameters" } }, "expertSettings": { "description": "Dictionary of custom options.\n", "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.\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios.\n", "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. \n\nExample response:\n```json\n {\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"categories\": [\"Electronics\", \"Televisions\"],\n \"price\": 342,\n \"url\": \"myshop.com/tv-178\"\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"categories\": [\"Home & Kitchen\"],\n \"price\": 39,\n \"url\": \"myshop.com/mixer-42\"\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nExample response for `includedProperties=description,price`:\n```json\n {\n \"recommId\": \"a86ee8d5-cd8e-46d1-886c-8b3771d0520b\",\n \"recomms\":\n [\n {\n \"id\": \"tv-178\",\n \"values\": {\n \"description\": \"4K TV with 3D feature\",\n \"price\": 342\n }\n },\n {\n \"id\": \"mixer-42\",\n \"values\": {\n \"description\": \"Stainless Steel Mixer\",\n \"price\": 39\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n }\n```\n", "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.\n\nFilters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\n\nBoosters can also be assigned to a [scenario](https://docs.recombee.com/scenarios) in the [Admin UI](https://admin.recombee.com).\n", "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.\nThis can be used to compute additional properties of the recommended items that are not stored in the database.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"isInUsersCity\": \"context_user[\\\"city\\\"] in 'cities'\",\n \"distanceToUser\": \"earth_distance('location', context_user[\\\"location\\\"])\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"ce52ada4-e4d9-4885-943c-407db2dee837\",\n \"recomms\": \n [\n {\n \"id\": \"restaurant-178\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": true,\n \"distanceToUser\": 5200.2\n }\n },\n {\n \"id\": \"bar-42\",\n \"reqlEvaluations\": {\n \"isInUsersCity\": false,\n \"distanceToUser\": 2516.0\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "type": "object", "additionalProperties": { "type": "string" } }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "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\".\n\nYou 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.\n\nThe AI that optimizes models to get the best results may optimize different scenarios separately or even use different models in each of the scenarios.\n", "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.\n", "type": "boolean" }, "filter": { "description": "Boolean-returning [ReQL](https://docs.recombee.com/reql) expression which allows you to filter recommended segments based on the `segmentationId`.\n", "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`.\n", "type": "string" }, "logic": { "$ref": "#/components/schemas/Logic" }, "expertSettings": { "description": "Dictionary of custom options.\n", "type": "object" }, "returnAbGroup": { "description": "If there is a custom AB-testing running, return the name of the group to which the request belongs.\n", "type": "boolean" }, "reqlExpressions": { "description": "A dictionary of [ReQL](https://docs.recombee.com/reql) expressions that will be executed for each recommended Item Segment.\nThis can be used to compute additional properties of the recommended Item Segments.\n\nThe keys are the names of the expressions, and the values are the actual ReQL expressions.\n\nExample request:\n```json\n{\n \"reqlExpressions\": {\n \"countItems\": \"size(segment_items(\\\"categories\\\", 'segmentId'))\"\n }\n}\n```\n\nExample response:\n```json\n{\n \"recommId\": \"a7ac55a4-8d6e-4f19-addc-abac4164d8a8\",\n \"recomms\": \n [\n {\n \"id\": \"category-fantasy-books\",\n \"reqlEvaluations\": {\n \"countItems\": 486\n }\n },\n {\n \"id\": \"category-sci-fi-costumes\",\n \"reqlEvaluations\": {\n \"countItems\": 19\n }\n }\n ],\n \"numberNextRecommsCalls\": 0\n}\n```\n", "type": "object", "additionalProperties": { "type": "string" } } } }, "RecommendNextItemsParameters": { "type": "object", "required": [ "count" ], "properties": { "count": { "description": "Number of items to be recommended\n", "type": "integer" } } }, "CreatePropertyBasedSegmentationParameters": { "type": "object", "required": [ "sourceType", "propertyName" ], "properties": { "sourceType": { "description": "What type of data should be segmented. Currently only `items` are supported.\n", "type": "string" }, "propertyName": { "description": "Name of the property on which the Segmentation should be based\n", "type": "string" }, "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "type": "string" } } }, "UpdatePropertyBasedSegmentationParameters": { "type": "object", "properties": { "propertyName": { "description": "Name of the property on which the Segmentation should be based\n", "type": "string" }, "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "type": "string" } } }, "CreateAutoReQLSegmentationParameters": { "type": "object", "required": [ "sourceType", "expression" ], "properties": { "sourceType": { "description": "What type of data should be segmented. Currently only `items` are supported.\n", "type": "string" }, "expression": { "description": "ReQL expression that returns for each item a set with IDs of segments to which the item belongs\n", "type": "string" }, "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "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\n", "type": "string" }, "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "type": "string" } } }, "CreateManualReQLSegmentationParameters": { "type": "object", "required": [ "sourceType" ], "properties": { "sourceType": { "description": "What type of data should be segmented. Currently only `items` are supported.\n", "type": "string" }, "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "type": "string" } } }, "UpdateManualReQLSegmentationParameters": { "type": "object", "properties": { "title": { "description": "Human-readable name that is shown in the Recombee Admin UI.\n", "type": "string" }, "description": { "description": "Description that is shown in the Recombee Admin UI.\n", "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`.\n", "type": "string" }, "title": { "description": "Human-readable name of the Segment that is shown in the Recombee Admin UI.\n", "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.\nThe keys are the names of the ReQL expressions, and the values are the results of the evaluations.\n" } } }, "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.\n\nDefault: `false`.\n" } } }, "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.\n" } } }, "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" } } } } } } }