miso.ai Product Recommendations API
APIs for recommending related products based on a given product.
OpenAPI Specification
openapi: 3.0.2
info:
title: Miso Ask APIs Product 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: Product Recommendations
description: APIs for recommending related products based on a given product.
paths:
/v1/recommendation/product_to_products:
post:
tags:
- Product Recommendations
summary: Product to Products API
description: "The Product to Products API returns the products that are related to an anchor product (often the product the user\nis currently engaging with) and are also likely to drive conversions by connecting with the user’s interests. It is\ndifferent from the User to Products API as it not only considers the user’s interests but also considers the\nrecommended products' relevancy to the anchor product.\n\n### Applicable scenarios\nThis API is frequently used in product detail page to show related products that users can consume\nfurther, such as \"Related products you may like\" on Amazon or \"Up next video\" on Youtube. It is one of Miso's best\nperforming APIs. Our customers usually see more than 30% and some times 110% relative lift in click-through rate after\ndeploying this a feature using this API.\n\n### Basic usage\nTo use this API, you just need to let Miso knows the `user_id` (or `anonymous_id`) and the `product_id` you\nwant to get related recommendations for. For example, the following request will return the products that are\nrelated to the movie `Toy Story`.\n```\nPOST https://api.askmiso.com/v1/recommendation/product_to_products\n{\n \"user_id\": \"user_123\",\n \"product_id\": [\"toy-story-1995\"],\n \"rows\": 3,\n \"fl\": [\"title\"]\n}\n```\n* **product_id**: the id of the anchor product\n* **rows**: the number of related products to return\n* **fl**: like in other Miso API, you can use `fl` to control which fields to return for each Product\n\nThe response will be like:\n```javascript\n{\n \"message\": \"success\",\n \"data\": {\n \"took\": 56,\n \"miso_id\": \"f98b1904-ddce-11eb-be53-fa1729b23183\",\n \"products\": [\n {\n \"product_id\": \"toy-story-2-1999\",\n \"title\": \"Toy Story 2 (1999)\"\n },\n {\n \"product_id\": \"toy-story-3-2010\",\n \"title\": \"Toy Story 3 (2010)\"\n },\n {\n \"product_id\": \"the-lion-king-1994\",\n \"title\": \"The Lion King (1994)\"\n }\n ]\n }\n}\n```\n* **products**: a list of products related to the anchor product\n* **products[ ].product_id**: the id of the recommended product\n* **products[ ].title**: the title of the recommended product. You can use `fl` parameter to make Miso return more fields\n\n### Boosting and filtering\nLike every Miso API, you can utilize `fq` and `boost_fq` to fine-tune the recommendations returned by Miso, and\nMiso will guarantee to return the required number of recommendations that meet the given criteria.\n\nFor example, the following request still recommends movies related to \"Toy Story\" but limits the recommendations\nto only the movies released after year 2010.\n```\nPOST https://api.askmiso.com/v1/recommendation/product_to_products\n{\n \"user_id\": \"user_123\",\n \"product_id\": [\"toy-story-1995\"],\n \"rows\": 3,\n \"fl\": [\"title\"],\n \"fq\": \"custom_attributes.year: [2010 TO *]\"\n}\n```\n\nFor another example, the following request will *boost* the movies that are acted by `Tom Hanks`. The boosting is\ndifferent from filtering as it only prioritizes those products that match the boosting criteria and are relevant to\nthe anchor products, but it will not limit the results to only such products.\n```\nPOST https://api.askmiso.com/v1/recommendation/product_to_products\n{\n \"user_id\": \"user_123\",\n \"product_id\": [\"toy-story-1995\"],\n \"rows\": 3,\n \"fl\": [\"title\"],\n \"boost_fq\": \"custom_attributes.actors:\\\"Tom Hanks\\\"\"\n}\n```\n\n### Multiple anchor products\nIn the scenarios where you want to recommend products related to **multiple** anchor products, for example,\nfor shopping cart cross-sell or up-sell, you can utilize `product_ids`\nparameter and have multiple product ids in it.\n\nFor instance, the following request recommends products related to movies \"Toy Story\" and \"Monsters, Inc.\"\nthat will be of interest to the the current user.\n```\nPOST https://api.askmiso.com/v1/recommendation/product_to_products\n{\n \"user_id\": \"user_123\",\n \"product_ids\": [\"toy-story-1995\", \"monsters-inc-2001\"],\n \"rows\": 3,\n \"fl\": [\"title\"]\n}\n```"
operationId: product_to_products_v1_recommendation_product_to_products_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/YMALRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ProductToProductsResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
components:
schemas:
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 timestamp to provide a higher time resolution.
Example:
```
{"timestamp": "2018-11-07T00:25:00.073876Z"}
```
'
format: date-time
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
example: 123e4567-e89b-12d3-a456-426614174000
context:
title: Context
allOf:
- $ref: '#/components/schemas/WebBasedContext'
description: "\nDictionary of extra information that provides useful context about an interaction. We use context\ninformation to make recommendations tailored not only for each user, but also for their current browsing context.\nFor example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile\nphone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very\ndifferent interests than a user who visits your site directly.\n\nContext information is also useful for personalization for entirely new visitors, as we can immediately\npersonalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through).\n\nExample:\n```\n{\"context\": {\n \"campaign\":\n {\n \"name\": \"spring_sale\",\n \"source\": \"Google\",\n \"medium\": \"cpc\",\n \"term\": \"running+shoes\",\n \"content\": \"textlink\"\n },\n \"truncated_ip\": \"1.1.1.0\",\n \"locale\": \"en-US\",\n \"region\": \"US East\",\n \"page\":\n {\n \"url\": \"https://example.com/miso-tshirt-123ABC\",\n \"referrer\": \"https://example.com/\",\n \"title\": \"My Product Page\"\n },\n \"user_agent\": \"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)\"\n },\n \"custom_context\": {\n \"other_context_var_1\": \"value_1\",\n \"other_context_var_2\": \"value_2\"\n }\n}\n```\n"
additionalProperties: false
AddToCollection:
title: add_to_collection
required:
- type
type: object
properties:
type:
title: Type
enum:
- add_to_collection
type: string
description: '
Used when a user adds a product to their personal collection. This is a strong
signal of their interest in the product.
'
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 timestamp to provide a higher time resolution.
Example:
```
{"timestamp": "2018-11-07T00:25:00.073876Z"}
```
'
format: date-time
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
example: 123e4567-e89b-12d3-a456-426614174000
context:
title: Context
allOf:
- $ref: '#/components/schemas/WebBasedContext'
description: "\nDictionary of extra information that provides useful context about an interaction. We use context\ninformation to make recommendations tailored not only for each user, but also for their current browsing context.\nFor example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile\nphone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very\ndifferent interests than a user who visits your site directly.\n\nContext information is also useful for personalization for entirely new visitors, as we can immediately\npersonalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through).\n\nExample:\n```\n{\"context\": {\n \"campaign\":\n {\n \"name\": \"spring_sale\",\n \"source\": \"Google\",\n \"medium\": \"cpc\",\n \"term\": \"running+shoes\",\n \"content\": \"textlink\"\n },\n \"truncated_ip\": \"1.1.1.0\",\n \"locale\": \"en-US\",\n \"region\": \"US East\",\n \"page\":\n {\n \"url\": \"https://example.com/miso-tshirt-123ABC\",\n \"referrer\": \"https://example.com/\",\n \"title\": \"My Product Page\"\n },\n \"user_agent\": \"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)\"\n },\n \"custom_context\": {\n \"other_context_var_1\": \"value_1\",\n \"other_context_var_2\": \"value_2\"\n }\n}\n```\n"
additionalProperties: false
ValidationError:
title: ValidationError
required:
- loc
- msg
- type
type: object
properties:
loc:
title: Location
type: array
items:
type: string
msg:
title: Message
type: string
type:
title: Error Type
type: string
Bookmark:
title: bookmark
required:
- type
type: object
properties:
type:
title: Type
enum:
- bookmark
type: string
description: '
Used when a user bookmarks a product.
'
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 timestamp to provide a higher time resolution.
Example:
```
{"timestamp": "2018-11-07T00:25:00.073876Z"}
```
'
format: date-time
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
example: 123e4567-e89b-12d3-a456-426614174000
context:
title: Context
allOf:
- $ref: '#/components/schemas/WebBasedContext'
description: "\nDictionary of extra information that provides useful context about an interaction. We use context\ninformation to make recommendations tailored not only for each user, but also for their current browsing context.\nFor example, a user browsing on a desktop may have different browsing behavior than a user browsing on mobile\nphone. As another example, a user who gets to the site via a certain campaign you run on Facebook may have very\ndifferent interests than a user who visits your site directly.\n\nContext information is also useful for personalization for entirely new visitors, as we can immediately\npersonalize their experiences based on their context alone (e.g. the referrer or the campaign they clicked through).\n\nExample:\n```\n{\"context\": {\n \"campaign\":\n {\n \"name\": \"spring_sale\",\n \"source\": \"Google\",\n \"medium\": \"cpc\",\n \"term\": \"running+shoes\",\n \"content\": \"textlink\"\n },\n \"truncated_ip\": \"1.1.1.0\",\n \"locale\": \"en-US\",\n \"region\": \"US East\",\n \"page\":\n {\n \"url\": \"https://example.com/miso-tshirt-123ABC\",\n \"referrer\": \"https://example.com/\",\n \"title\": \"My Product Page\"\n },\n \"user_agent\": \"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0)\"\n },\n \"custom_context\": {\n \"other_context_var_1\": \"value_1\",\n \"other_context_var_2\": \"value_2\"\n }\n}\n```\n"
additionalProperties: false
Checkout:
title: checkout
required:
- type
type: object
properties:
type:
title: Type
enum:
- checkout
type: string
description: '
Used when a user enters checks out with a set of products. For an eCommerce site, this is the strongest signal of the user''s
interest and has a high probability of leading to an eventual purchase.
'
revenue:
title: Revenue
type: number
description: '
Total revenue associated with the checkout. The revenue should include generally shipping, tax, etc. that you
want to include as part of your revenue calculations.
'
example: 23.32
quantities:
title: Quantities
anyOf:
-
# --- truncated at 32 KB (247 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/misoai/refs/heads/main/openapi/misoai-product-recommendations-api-openapi.yml