openapi: 3.0.2
info:
title: Miso Ask APIs Interaction APIs 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: Interaction APIs
description: "\nMiso’s Interaction APIs let you manage your Interaction records stored with Miso.\n\n### Interaction records\nYour Interaction records tell Miso about user interactions with products and content on your site or application.\nFrom these interactions, Miso understands how users move through your conversion funnels: which products or content\nassets attract the attention of each individual user, and which products or content ultimately will be purchased or\nconsumed by each of them. With these insights, Miso makes real-time tailored recommendations for each user, and\nresponds to each of their clicks and views on the site (even for anonymous users).\n\nInteraction records share some common attributes, but are distinguished by their type.\nMiso captures 23 different interaction types, divided into the following 6 groups:\n\n#### Core click-streams\n* `product_detail_page_view`: a user viewed the detail page for a product\n* `search`: a user made a search request with keywords and (optionally) filters\n\nThe above interactions are the core fuel for Miso's personalization Engines, because they happen in a much higher\nfrequency than other interactions and provide an unbiased and high-fidelity view of users' interests on the site.\nThe collection of these interactions is highly important for Miso's personalization performance. At the minimum,\nyou should implement the `product_detail_page_view` interaction to start with.\n\n#### Conversion (eCommerce)\n* `add_to_cart`: a user added a product to the shopping cart\n* `remove_from_cart`: a user removed a product from the shopping cart\n* `checkout`: a user checked out and started the payment process\n* `refund`: a user refunded the product\n* `subscribe`: a user subscribed to a product\n\nThe above interactions are the main revenue drivers for eCommerce sites. It’s important to collect them so that\nMiso can not only drive click-through rates, but actually improve the revenue in a targeted way. To start with,\nyou should at least implement the `add_to_cart` interaction.\n\n#### Consumption (content media)\n* `read`, `watch`, and `listen` interactions capture how and for how long a user consumed a piece of content.\n* `add_to_collection`: a user added an product to their personal collection\n* `remove_from_collection`: a user removed an product from their personal collection\n\nIf you are a content site, the above interactions are the main drivers to users' satisfaction on the site.\nCollecting these interactions allows Miso to drive consumption rates and consumption durations for the content on\nyour site. If you run a content site, you should implement at least one of these interactions.\n\n#### Feedback signals\n* `like`, `dislike`, `share`, `rate`, and `bookmark` are common ways users express their interests.\n\nThese are strong signals for Miso to understand each user's preferences regarding your products or content. You\nshould send these signals to Miso if you have any of these UI patterns on your site.\n\n#### Performance Checking\n* `impression`: a user saw or was presented with a product or content asset (but didn't yet interact with it)\n* `viewable_impression`: the product or content presented is actually viewed by the user\n (for example, minimum of 50% of the pixels were in viewable space for at least one continuous second.)\n* `click`: a user clicked on something (for example, a product item)\n\n#### Additional click-streams\n* `home_page_view`: user viewed your home page\n* `category_page_view`: a user viewed the page for a specific “group” or “family” or products or content in your catalog\n* `promo_page_view`: user viewed the promotion pages about certain products\n* `product_image_view`: user clicked on or otherwise interacted with the product image (e.g. enlarged the image)\n\nThe above interactions are additional signals for Miso to understand users' behavior on the site.\n\n#### Custom\n* `custom` interaction types are reserved for you to define your own business-specific interaction types.\n\nMiso will analyze any custom interactions you define to infer users' interests and preferences.\n\n\n"
paths:
/v1/interactions:
post:
tags:
- Interaction APIs
summary: Interaction Upload API
description: "Miso’s Interaction APIs let you manage your Interaction records stored with Miso.\n\n### Interaction records\nYour Interaction records tell Miso about user interactions with products and content on your site or application.\nFrom these interactions, Miso understands how users move through your conversion funnels: which products or content\nassets attract the attention of each individual user, and which products or content ultimately will be purchased or\nconsumed by each of them. With these insights, Miso makes real-time tailored recommendations for each user, and\nresponds to each of their clicks and views on the site (even for anonymous users).\n\nInteraction records share some common attributes, but are distinguished by their type.\nMiso captures 23 different interaction types, divided into the following 6 groups:\n\n#### Core click-streams\n* `product_detail_page_view`: a user viewed the detail page for a product\n* `search`: a user made a search request with keywords and (optionally) filters\n\nThe above interactions are the core fuel for Miso's personalization Engines, because they happen in a much higher\nfrequency than other interactions and provide an unbiased and high-fidelity view of users' interests on the site.\nThe collection of these interactions is highly important for Miso's personalization performance. At the minimum,\nyou should implement the `product_detail_page_view` interaction to start with.\n\n#### Conversion (eCommerce)\n* `add_to_cart`: a user added a product to the shopping cart\n* `remove_from_cart`: a user removed a product from the shopping cart\n* `checkout`: a user checked out and started the payment process\n* `refund`: a user refunded the product\n* `subscribe`: a user subscribed to a product\n\nThe above interactions are the main revenue drivers for eCommerce sites. It’s important to collect them so that\nMiso can not only drive click-through rates, but actually improve the revenue in a targeted way. To start with,\nyou should at least implement the `add_to_cart` interaction.\n\n#### Consumption (content media)\n* `read`, `watch`, and `listen` interactions capture how and for how long a user consumed a piece of content.\n* `add_to_collection`: a user added an product to their personal collection\n* `remove_from_collection`: a user removed an product from their personal collection\n\nIf you are a content site, the above interactions are the main drivers to users' satisfaction on the site.\nCollecting these interactions allows Miso to drive consumption rates and consumption durations for the content on\nyour site. If you run a content site, you should implement at least one of these interactions.\n\n#### Feedback signals\n* `like`, `dislike`, `share`, `rate`, and `bookmark` are common ways users express their interests.\n\nThese are strong signals for Miso to understand each user's preferences regarding your products or content. You\nshould send these signals to Miso if you have any of these UI patterns on your site.\n\n#### Performance Checking\n* `impression`: a user saw or was presented with a product or content asset (but didn't yet interact with it)\n* `viewable_impression`: the product or content presented is actually viewed by the user\n (for example, minimum of 50% of the pixels were in viewable space for at least one continuous second.)\n* `click`: a user clicked on something (for example, a product item)\n\n#### Additional click-streams\n* `home_page_view`: user viewed your home page\n* `category_page_view`: a user viewed the page for a specific “group” or “family” or products or content in your catalog\n* `promo_page_view`: user viewed the promotion pages about certain products\n* `product_image_view`: user clicked on or otherwise interacted with the product image (e.g. enlarged the image)\n\nThe above interactions are additional signals for Miso to understand users' behavior on the site.\n\n#### Custom\n* `custom` interaction types are reserved for you to define your own business-specific interaction types.\n\nMiso will analyze any custom interactions you define to infer users' interests and preferences.\n\nBulk API to insert Interaction records. This endpoint accepts POST requests with JSON data containing an array of\nInteraction records wrapped in a dictionary:\n\n```\nPOST /v1/interactions\n\n{\"data\": [interaction_1, interaction_2, interaction_3]}\n```\n\nFor real-time tracking, we recommend sending the interaction records to this API as soon as the interactions take\nplace. This API is also ideal for bulk-inserting historical records that your site collected before using Miso.\n Miso can analyze the historical records and provide personalization for your users from the get-go. We recommend\n limiting your calls to around 10,000 records at a time to avoid memory issues or timeout risks.\n\n### Anonymous users\nFor users who did not sign in, we can still make recommendations for them by tracking their `anonymous_id`, which is a pseudo-unique substitute for the `user_id`. The personalization and search APIs all accept `anonymous_id` in the place of `user_id` to return tailored results for anonymous users.\n\nWhen an anonymous user later signs in and the `user_id` and `anonymous_id` are both present, the `anonymous_id` will be linked to the `user_id` along with the past interactions associated with it.\n\nThe typical mechanism to generate an `anonymous_id` is to use cookies or the browser localStorage. However, if you don't collect such information in your historical records, a hash of the IP address, optionally combined with the User-Agent string, is also a reasonable substitute for `anonymous_id`, and is most likely collected by your web server logs already.\n\n### Schema validation\nThe Interaction Upload API will validate the inserted records against the API schema.\nAny schema errors will cause the whole request to fail, and none of the records will be inserted (`status_code=422`).\nYou should check the `response.errors` field to see if there are any errors.\n\nFor example, the response below means there are no errors (`status_code=200`):\n```javascript\n{\n \"message\": \"success\"\n}\n```\n\nAny schema error will cause the whole request to fail: the API will return `status_code=422`, and none of the\nrecords will be inserted. You should check `data` field in the response to see where the errors are located. For\nexample, the response below means there are schema errors in the interaction record at index 0:\n```javascript\n{\n \"errors\": true, // there are errors. please check!\n \"message\": \"None of the records were inserted because at least one of them contained schema errors. Please see the `data` field for details.\",\n \"data\": [\n \"data.0.product_ids is invalid. The attribute was expected to be of type ''array', 'null'' but type 'string' was given.\",\n \"data.0.timestamp is invalid. The attribute should match the 'date-time' format.\"\n ]\n}\n```"
operationId: interaction_upload_api_v1_interactions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InteractionBulkIn'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InteractionCreateOut'
'401':
description: Unauthorized
content:
application/json:
example:
message: invalid api key.
'403':
description: Forbidden
content:
application/json:
example:
message: Request is denied due to bot blocking. Please only access this API from a real browser or use Secret API Key instead.
'422':
description: Unprocessable Entity
content:
application/json:
example:
errors: true
message: None of the records were inserted because at least one of them contained schema errors. Please see the `data` field for details.
data:
- data.0.product_ids is invalid. The attribute was expected to be of type ''array', 'null'' but type 'string' was given.
- data.0.timestamp is invalid. The attribute should match the 'date-time' format.
security:
- Secret API Key: []
- Publishable API Key: []
delete:
tags:
- Interaction APIs
summary: Interaction Delete API
description: 'The endpoint will delete users'' interaction data entirely from the log of interactions you have uploaded to Miso.
This API enables you to comply with users'' data removal requests (i.e. right to be forgotten). Once a user''s
interactions are deleted, we will not be able to recover them, and they will no longer contribute to model
training.'
operationId: interaction_delete_api_v1_interactions_delete
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InteractionDeleteIn'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/InteractionDeleteOut'
'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 \
# --- truncated at 32 KB (226 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/misoai/refs/heads/main/openapi/misoai-interaction-apis-api-openapi.yml