miso.ai User Recommendations API
APIs for recommending products and content to users based on their interests.
OpenAPI Specification
openapi: 3.0.2
info:
title: Miso Ask APIs User Recommendations API
description: '
# Overview
Miso’s approach to personalization is to train machine learning Engines on three core data sets:
1. Your site’s log of historical and real-time interactions,
2. Your catalog of products and content, and
3. Your users. Miso provides the output of its Engines to you, so you can build search and recommendation
experiences that are personalized down to the individual level (n=1 personalization).
To see how Miso works and explore the power of its Engines, we recommend following
[this tutorial](https://docs.askmiso.com/) to get
started with our Playground data. Integrating your site or application with Miso happens in three basic steps:
1. Upload your data
2. Train your Engines
3. Build search and recommendation experiences with the output of your Engines.
Miso provides two main integration points. The first is your [Dojo Dashboard](https://dojo.askmiso.com/),
which is used to set up your Engines with the conversions you want to optimize and your training schedule.
Dojo is also a great way to get familiar with Miso by manually uploading data and exploring the output of
Miso’s Engines. In Dojo’s Sandboxes, you can tweak your Engine settings and see visual examples of Miso’s search
and recommendations running on your live data.
The second integration point is Miso’s API, which lets you automatically manage your data in Miso and build
experiences that leverage the output of Miso’s personalization Engines.
Miso’s API is composed of two major groups of REST API endpoints: Data APIs and Engine APIs.
### Data APIs
Data APIs collect input to Miso''s personalization Engines. These APIs all support high-throughput
data ingestion through bulk insert, and satisfy GDPR and CCPA compliance by letting users delete their data
from Miso. Subcategories of Data APIs are:
* [Interaction APIs](#tag/Interaction-APIs), for managing your Interaction records. By uploading historical and real-time Interaction
records, you tell Miso how users are engaging with the products and content on your site, and in turn, Miso’s
Engines learn how to optimize your conversion funnels.
* [Product / Content APIs](#tag/Product-Content-APIs), for managing your Product / Content records. These records provide a deep semantic
understanding of your catalog and keep Miso up to date about your offerings so it can make smart and timely
suggestions. The `product_id` is how Miso links Product / Content records to your Interaction records.
* [User APIs](#tag/User-APIs), for managing your User records. These records tell Miso about your site’s users and visitors,
so Miso can build an understanding of user segmentation and behavior in relation to products and content.
The `user_id` is how Miso links User records to your Interaction records.
As a rule of thumb, we recommend batching up data to avoid timeout risks. For the Product / Content and User
Upload APIs, we recommend limiting each API upload call to about 100 records at a time. For the Interaction
Upload API, we recommend limiting your calls to around 10,000 records at a time.
### Engine APIs
Engine APIs provide the output of Miso''s personalization Engines. We designed these APIs with a focus on low
latency and high availability. Most of these APIs'' 95th percentile response time is under 75ms,
and the services are replicated to at least three separate instances for high availability.
The types of Engine APIs are:
* [Search APIs](#tag/Search-APIs), for getting Miso’s personalized search results for a user, with search-as-you-type and
autocompletion.
* [Recommendation APIs](#tag/Recommendation-APIs), for retrieving Miso’s recommendations that match users with
the products, categories, and product attributes that are likely to drive conversions.
# Authentication
[View your API Keys in your Dojo Dashboard.](https://dojo.askmiso.com/docs/api-browser)
There are three environments in Miso:
* **Playground**, a read-only tutorial environment with sample data.
* **Development**, for staging, QA, and experimentation.
* **Production**, where you run your live integration with Miso.
Access a Miso environment by passing in the corresponding API key in your API calls. There is one publishable
key and one secret key per environment.
API Key can passed with query parameter `api_key`, or using the `X-API-KEY` header.
'
version: 1.1.4
servers:
- url: https://api.askmiso.com
tags:
- name: User Recommendations
description: APIs for recommending products and content to users based on their interests.
paths:
/v1/recommendation/user_to_products:
post:
tags:
- User Recommendations
summary: User to Products API
description: "Returns the products that are most likely to drive conversion for the given user. Depending on the conversion\nmetrics you choose when training your Miso Engines in Dojo, this API returns products that are most likely to\noptimize those metrics (such as `add_to_cart`, `checkout`, or `read`).\n\nThis API considers both user's interests and the conversion probability. The user's interests are determined from\ntheir past interactions on the site and the context of their current browsing session, including recent trending\nproducts, time of the day, recent search behaviors, etc.\n\n### Application scenarios\nThe User to Products API is usually used in homepage recommendations, such as \"*Inspired by your shopping trends*\" on\nAmazon, or \"*Recommended videos*\" on Youtube. It can also be used to run an email marketing campaign such as a\nnewsletter from Medium with recent articles you might like. These kind of recommendations are particularly powerful\nin driving product discovery.\n\n### Basic usage\nFor basic usage of this API, you just need to let Miso knows the id of the current user or visitor via `user_id`\nor `anonymous_id` field. For example, for a currently logged-in user, your request may look like the following:\n```\nPOST /v1/recommendation/user_to_products\n{\"user_id\": \"user-123\"}\n```\nFor a un-signed visitor, your request may look like the following:\n```\nPOST /v1/recommendation/user_to_products\n{\"anonymous_id\": \"visitor-123\"}\n```\n\nThis API will respond with the recommended products for the specified user or visitor:\n```javascript\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 37,\n \"miso_id\": \"517452b0-0ccf-11eb-948d-66359cf29022\",\n \"products\": [\n {\n \"product_id\": \"tmdb-475557\",\n \"_personalization_score\": 0.91\n },\n {\n \"product_id\": \"tmdb-299534\",\n \"_personalization_score\": 0.89\n },\n ...\n ]\n }\n}\n```\n* **took**: the amount of time (in milliseconds) Miso took to answer the query\n* **miso_id**: a UUID of the search request. You should include **miso_id** in the Interaction records for every\ninteractions that result from this search request, e.g. user click-through a product in the search results.\nMiso use miso_id to track the search performance and fine-tune the algorithm accordingly.\n* **products**: an array of [Product records](#operation/content_write_api_v1_products_post) recommended to this\nuser ranked by the probability that the user will be interested in this product. By default, only the `product_id`\nof the Product is returned. You can ask Miso to return additional fields by using the *fl* request argument (see example below)\n* **products[ ]._personalization_score**: the score assigned by Miso's personalization algorithm based on users'\nprofile and their interactions on the site. This score quantifies the probability of whether users will be\ninterested in this product or not.\n\nYou can use the `fl` request argument to ask Miso to return more product fields. For example, the following request\nasks Miso to additionally return the *title* and *category* fields of every recommended product:\n```\nPOST /v1/recommendation/user_to_products\n{\n \"user_id\": \"user-123\",\n \"fl\": [\"title\", \"categories\"]\n}\n```\nThe response will be like:\n```javascript\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 37,\n \"miso_id\": \"517452b0-0ccf-11eb-948d-66359cf29022\",\n \"products\": [\n {\n \"product_id\": \"tmdb-475557\",\n \"categories\": [\n [\n \"Crime\"\n ],\n [\n \"Thriller\"\n ],\n [\n \"Drama\"\n ]\n ],\n \"title\": \"Joker (2019)\",\n \"_personalization_score\": 0.91\n },\n {\n \"product_id\": \"tmdb-299534\",\n \"categories\": [\n [\n \"Adventure\"\n ],\n [\n \"Science Fiction\"\n ],\n [\n \"Action\"\n ]\n ],\n \"title\": \"Avengers: Endgame (2019)\",\n \"_personalization_score\": 0.89\n },\n ...\n ]\n }\n}\n```\n### Filtering and Boosting\nLike every other Miso API, `User To Products` API supports filter query (`fq`) and boost query (`boost_fq`) to\ngenerate recommendations that meet your business needs.\n\n#### Filter Query\nYou can use filter query to filter recommendation results against\narbitrary criteria, and Miso will *guarantee* to return sufficient number of recommendation results that meet the\ncriteria. For example, the following requests will limit the recommendations to only `Drama` films:\n```\nPOST /v1/recommendation/user_to_products\n{\n \"user_id\": \"user-123\",\n \"fl\": [\"title\", \"categories\"],\n \"fq\": \"categories:Drama\"\n}\n```\n\nFor another example with `custom_attributes`, the following requests will limit the recommendations to\n only `Drama` films after `2010`:\n```\nPOST /v1/recommendation/user_to_products\n{\n \"user_id\": \"user-123\",\n \"fl\": [\"title\", \"categories\"],\n \"fq\": \"categories:Drama AND custom_attributes.year:[2010 to *]\"\n}\n```\n\n#### Latency Consideration\nMiso achieves **instant** recommendations by pre-computing a large pool of candidates (N>1,000)\nfor each user with the products they are mostly likely to be interested in. However, when the given filter query do\nnot match a sufficient number of\ncandidates, Miso will fall back to Search API to find additional matches to fill in the remaining\nslots. While falling back to Search API will increase the latency, the latency increase is usually minimum if the\nsame filter query is being used repeatedly due to Miso's caching mechanism.\n\n\n#### Boost Query\nYou can use `boost_fq` to boost Products with arbitrary criteria. The relevant Products that match the `boost_fq`\nwill be ranked at the top of the recommendations or at the positions specified in the\n`boost_positions` parameter. Boosting is particularly useful for product promotions (e.g. sponsored products) to\nhighlight the Products you want more impression.\n\nFor example, the following request will boost the `Sci-Fi` films directed by `Ridley Scott`:\n```\nPOST /v1/recommendation/user_to_products\n{\n \"user_id\": \"user-123\",\n \"fl\": [\"title\", \"categories\"],\n \"boost_fq\": \"categories:\\\"Sci-Fi\\\" AND custom_attributes.director:\\\"Ridley Scott\\\"\"\n}\n```\nThe response will be like:\n\n```javascript\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 83,\n \"miso_id\": \"54bf6d9a-dd32-11eb-99d6-a62d401473b5\",\n \"products\": [\n {\n \"product_id\": \"tmdb-286217\",\n \"title\": \"The Martian (2015)\",\n \"_personalization_score\": 0.5364759309088403,\n \"_boosted\": true,\n \"categories\": [\n [\n \"Drama\"\n ],\n [\n \"Adventure\"\n ],\n [\n \"Science Fiction\"\n ]\n ]\n },\n ...\n ]\n }\n}\n```\nThe additional field **products[ ].boosted** is a boolean that indicates whether the Product matches the `boost_fq`.\n\nYou can also use `boost_positions` to specify the positions in the recommendation list you want the\nboosted Products to be placed. For example, the following request will place the boosted Product at the second place,\nand the third place (the `boost_positions` are 0-based):\n\n```\nPOST /v1/recommendation/user_to_products\n{\n \"user_id\": \"user-123\",\n \"fl\": [\"title\", \"categories\"],\n \"boost_fq\": \"categories:\\\"Sci-Fi\\\" AND custom_attributes.director:\\\"Ridley Scott\\\"\",\n \"boost_positions\": [1, 2]\n}\n```\n\n### Filtering \"already seen\" items\nTypically, the User to Products API is used to let users discover new products they might be interested in. Therefore,\nit is important not to recommend products users have already interacted with recently. By default, the User to Products\nAPI filters out the most recent 50 products users have had interactions with (except for `impression` interactions)"
operationId: user_to_products_v1_recommendation_user_to_products_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserToItemsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/RecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
/v1/recommendation/user_to_categories:
post:
tags:
- User Recommendations
summary: User to Categories API
description: "The User to Categories API returns the product categories that will drive the conversion for the current user,\nalong with the recommended products for each returned category.\n\n### Application scenarios\nThis API is usually used in homepage recommendations, or category recommendations\nwhere recommendations are organized by categories,\nsuch as Netflix's \"*Action / Sci-Fi / Drama movies for you*\"\nor Amazon's \"*Recommendations for you in Grocery & Gourmet Food*\". The goal of such recommendations is to help\nusers discover attractive products under the categories they\nhave a high chance to be interested in.\n\n### Basic usage\nFor basic usage of this API, you just need to let Miso knows the `user_id` or\n`anonymous_id` of the current users. Miso will return a list of top categories along with the recommended\nProducts under each of the categories.\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_categories\n{\n \"user_id\": \"user-123\",\n \"rows\": 2,\n \"products_per_category\": 3,\n \"fl\": [\"title\"]\n}\n```\n* **rows**: the number of categories to return\n* **products_per_category**: the number of Products to return per each category\n* **fl**: like in other Miso API, you can use `fl` to control which fields to return for each Product\n\nThe response of this request will be like:\n```\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 85,\n \"miso_id\": \"7cd6059c-dd54-11eb-8050-a62d401473b5\",\n \"categories\": [\n {\n \"category\": [\n \"Drama\"\n ],\n \"total\": 61510,\n \"recommended_products\": [\n {\n \"product_id\": \"tmdb-286217\",\n \"title\": \"The Martian (2015)\"\n },\n {\n \"product_id\": \"tmdb-281957\",\n \"title\": \"The Revenant (2015)\"\n },\n {\n \"product_id\": \"tmdb-68718\",\n \"title\": \"Django Unchained (2012)\"\n }\n ]\n },\n {\n \"category\": [\n \"Thriller\"\n ],\n \"total\": 21870,\n \"recommended_products\": [\n {\n \"product_id\": \"tmdb-11324\",\n \"title\": \"Shutter Island (2010)\"\n },\n {\n \"product_id\": \"tmdb-1949\",\n \"title\": \"Zodiac (2007)\"\n },\n {\n \"product_id\": \"tmdb-1422\",\n \"title\": \"The Departed (2006)\"\n }\n ]\n }\n ]\n }\n}\n```\n* **categories**: a list of categories recommended to the users.\n* **categories[].category**: the recommended category in the format of category hierarchy. `[\"Sci-Fi\"]` is a top level category,\n`[\"Sci-Fi\", \"Space Travel\"]` is a second-level category under `Sci-Fi` (a.k.a subcategory).\n* **categories[].total**: the total number of Products belonging to the category\n* **categories[].recommended_products**: a list of Products (in that category) recommended to the users\n\n### Root Category\nBy default, `User To Categories` API recommends top level categories, but you can change this behavior\nvia `root_category` parameter. Miso will recommend the immediate sub-categories of the given `root_category`\nFor example, the following request will recommend sub-categories under\n`Science Fiction`, for example `[\"Science Fiction\", \"Space Travel\"]` or `[\"Science Fiction\", \"Steampunk\"]`:\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_categories\n{\n \"user_id\": \"test\",\n \"root_category\": [\"Science Fiction\"]\n}\n```\n\nIn some cases, you may want to get recommendations from *any* subcategories (regardless their parent category).\nIn such case, you can use wildcard `*` to achieve such results. For example, the following request will recommend\nany sub-categories regardless their parent category:\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_categories\n{\n \"user_id\": \"test\",\n \"root_category\": [\"*\"]\n}\n```\n### Filter and boost query\nLike every Miso API, `User To Categories` supports `fq` for filtering, and `boost_fq` for boosting. You can use\nthese parameters to make the recommendation results meet your exact business needs. For example, the following\nrequest will recommend categories\nthat contain sufficient number of Products that meet the `fq` criteria (i.e. films after 2010), and each Product\nreturned in the `recommended_products` list will also meet the `fq` criteria:\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_categories\n{\n \"user_id\": \"user-123\",\n \"rows\": 2,\n \"products_per_category\": 3,\n \"fq\": \"custom_attributes.year: [2010 TO *]\"\n}\n```\nSimilarly, you can use `boost_fq` to promote Products that meet your business criteria in each category. For example,\nthe following request will prioritize Products that are promoted (indicated by `custom_attributes.promoted`):\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_categories\n{\n \"user_id\": \"user-123\",\n \"rows\": 2,\n \"products_per_category\": 3,\n \"boost_fq\": \"custom_attributes.promoted: true\"\n}\n```\n### Latency considerations\n`User To Categories` API is one of more complex API because it needs to first identify categories the user will be\ninterested in, and then find the top Products in that categories. We make this process real-time by pre-computing a\nlarge number of top Products users may find interesting in for each category, therefore the end-to-end latency is\nusually under 100ms. To further reduce the latency, you can:\n* Use a smaller `products_per_category` to reduce number of products to return, or set it to zeros if you don't need any.\n* Request only the necessary fields using `fl` parameters\n* Use a smaller `rows` to reduce number of categories to return"
operationId: user_to_categories_v1_recommendation_user_to_categories_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserToCategories'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/CategoryRecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
/v1/recommendation/user_to_attributes:
post:
tags:
- User Recommendations
summary: User to Attributes API
description: "The `User to Attributes` API is a generalized version of `User to Categories` API --- it returns the product\nattributes that Miso expects to drive a conversion for the current\nuser. You specify a field in your Product catalog you want recommendations for, e.g. the `brand` or a custom field like\n`custom_attributes.director`, and this API will return a list of values from that fields Miso expects users will be most\ninterested in, as well as a list of personalized product suggestions.\n\n### Applicable scenarios\nThis API is usually used in homepage recommendations, where users can interact with recommended attributes.\nFor example, this API could generate suggestions for \"the brands you may like\" or \"the creators you may like.\"\n\n### Basic usage\nFor basic usage of this API, you just need to let Miso knows the `user_id` or `anonymous_id`, and the `field` you\nwant to get recommendations for. For example, the following request will return the recommended `director` for\nthe given users:\n```\nPOST https://api.askmiso.com/v1/recommendation/user_to_attributes\n{\n \"user_id\": \"test\",\n \"field\": \"custom_attributes.director\",\n \"rows\": 3,\n \"products_per_attribute\": 2,\n \"fl\": [\"title\"]\n}\n```\n* **field**: the name of the field you want to get recommendation for\n* **rows**: the number of categories to return\n* **products_per_attribute**: the number of Products to return per each attribute\n* **fl**: like in other Miso API, you can use `fl` to control which fields to return for each Product\n\nThe response of this request will be like:\n```javascript\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 296,\n \"miso_id\": \"9d7c8d9c-dd73-11eb-b20d-9a566192e5c6\",\n \"attributes\": [\n {\n \"value\": \"Christopher Nolan\",\n \"total\": 12,\n \"recommended_products\": [\n {\n \"product_id\": \"tmdb-272\",\n \"title\": \"Batman Begins (2005)\"\n },\n {\n \"product_id\": \"tmdb-77\",\n \"title\": \"Memento (2000)\"\n }\n ]\n },\n {\n \"value\": \"Ridley Scott\",\n \"total\": 26,\n \"recommended_products\": [\n {\n \"product_id\": \"tmdb-286217\",\n \"title\": \"The Martian (2015)\"\n },\n {\n \"product_id\": \"tmdb-4982\",\n \"title\": \"American Gangster (2007)\"\n }\n ]\n },\n {\n \"value\": \"Quentin Tarantino\",\n \"total\": 13,\n \"recommended_products\": [\n {\n \"product_id\": \"tmdb-680\",\n \"title\": \"Pulp Fiction (1994)\"\n },\n {\n \"product_id\": \"tmdb-68718\",\n \"title\": \"Django Unchained (2012)\"\n }\n ]\n }\n ]\n }\n}\n\n```\n* **attributes**: a list of attributes recommended to the users.\n* **attributes[ ].value**: the recommended attribute value (in this case, director name)\n* **attributes[ ].total**: the total number of Products that have this attribute\n* **attributes[ ].recommended_products**: a list of Products (with the attribute) recommended to the users"
operationId: user_to_attributes_v1_recommendation_user_to_attributes_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserToAttributes'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/AttributeRecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
/v1/recommendation/user_to_trending:
post:
tags:
- User Recommendations
summary: User to Trending API
description: 'The User to Trending API returns the products that are currently trending
and are most likely to be of interest to this user. It''s different from the User to Products API because it will only
recommend trending products. However, each user should still see unique recommendations that are not only trending but
also suit their interests.
### Applicable scenarios
This API is typically used to make homepage recommendations such as "Trending products for users like you" or
"Trending on Youtube".
### Filtering "already seen" items
The User to Trending API will not recommend products users have recently interacted with.'
operationId: trending_items_v1_recommendation_user_to_trending_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UserToItemsRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TrendRecResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
components:
schemas:
TrendResponseBody:
title: TrendResponseBody
required:
- products
type: object
properties:
took:
title: Took
type: integer
description: Number of milliseconds Miso took to retrieve the results.
default: 0
miso_id:
title: Miso Id
type: string
description: '
Miso-generated unique Id for each recommendation or search result. Maintaining this Id for
subsequent page views is important to Miso''s performance as we use `miso_id` to track and fine-tune the
performance of personalization and search results. When a user clicks on a recommendation or search result,
you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the
interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,
`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn''t.
Example:
```
{"misoId": "123e4567-e89b-12d3-a456-426614174000"}
```
'
format: uuid
default: 00000000-0000-0000-0000-000000000000
example: 123e4567-e89b-12d3-a456-426614174000
products:
title: Products
type: array
items:
$ref: '#/components/schemas/Record'
description: Trending product results.
PromoPageView:
title: promo_page_view
required:
- type
type: object
properties:
type:
title: Type
enum:
- promo_page_view
type: string
description: '
Used when a user views a specific promotional or curated marketing page about certain products or content.
'
duration:
title: Duration
type: number
description: '
How long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is
optional, but it''s very important in scenarios where consumption duration matters, including
`product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only
views or consumes a product for less than 5 seconds, that user is probably not interested in the product. On
the other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or
considering the product. When `duration` is absent, we will use the timestamp of the next interaction to
infer a rough duration value.
Example:
```
{"duration": 61.5}
```
'
example: 61.5
product_ids:
title: Product Ids
type: array
items:
type: string
maxLength: 512
description: '
Products or content the user is interacting with. This field is required by
almost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.
Therefore, it is important to keep this consistent between the two datasets.
Example:
```
{"product_ids": ["123ABC-BLACK", "123EFG-YELLOW"]}
```
'
default: []
example:
- 123ABC-BLACK
product_group_ids:
title: Product Group Ids
type: array
items:
type: string
maxLength: 512
description: '
The product groups the user is interacting with. You only need this field if you model product
variants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a
user is interacting with a *product group* rather than a specific product variant, for example, when the user
is viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or
color (i.e. a product variant) yet.
In such situations, the `product_id` is not applicable because we only know the user is interested in
this T-shirt (a product group), but don''t know which particular product variant the user is interested in.
Therefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.
In the situations where specific `product_ids` are available, for example, when user selected a particular size
of the T-Shirt, use `product_ids` instead.
Example:
```
{"product_group_ids": ["123ABC"]}
```
'
example:
- 123ABC
user_id:
title: User Id
maxLength: 512
type: string
description: "Identifies the signed-in user who performed the interaction. We will use `user_id` to link Interaction records to your\n User records. Therefore, it is important to keep this consistent between the two datasets.For visitors who have\n not signed in, see `anonymous_id`."
example: user_1234
anonymous_id:
title: Anonymous Id
maxLength: 1024
type: string
description: "A pseudo-unique substitute for the User Id. We use `anonymous_id` to identify a visitor who has not signed\n in. `anonymous_id` can be implemented using mechanisms such as cookies or browser localStorage. If `anonymous_id`\n is not given, we will default it to `SHA1(<API key>:<IP address>:<user agent>:<date>)`. When a visitor signs\n in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id`\n along with the past interactions associated with it."
example: 86D51273AD8BF84217E1567B6CBE7152D7034404
timestamp:
title: Timestamp
type: string
description: '
The ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we
will default to the server''s time. If you''re importing data from the past, make sure you provide a
timestamp. It is recommended to include milliseconds in the times
# --- truncated at 32 KB (300 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/misoai/refs/heads/main/openapi/misoai-user-recommendations-api-openapi.yml