)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"RecResponse": {
"title": "RecResponse",
"required": [
"data"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"default": "success"
},
"data": {
"$ref": "#/components/schemas/BaseResponseBody"
}
}
},
"Record": {
"title": "Record",
"required": [
"product_id"
],
"type": "object",
"properties": {
"product_id": {
"title": "Product Id",
"maxLength": 512,
"type": "string",
"description": "\n The unique identifier for the product.\n ",
"example": "123ABC-S-Black"
}
}
},
"RecordWithAnswer": {
"title": "RecordWithAnswer",
"required": [
"product_id",
"answer"
],
"type": "object",
"properties": {
"product_id": {
"title": "Product Id",
"maxLength": 512,
"type": "string",
"description": "The unique identifier of the product whose content contains the answer."
},
"answer": {
"title": "Answer",
"allOf": [
{
"$ref": "#/components/schemas/Answer"
}
],
"description": "The answer paragraph (i.e. a `` node) whose text content can answer users' question."
},
"answer_block": {
"title": "Answer Block",
"allOf": [
{
"$ref": "#/components/schemas/AnswerBlock"
}
],
"description": "\n In addition to the answer paragraph, we also return the **answer block**.\n Answer block is the ancestor node of the answer paragraph that cover not only the answer, but also the relevant\n context. This is particularly useful for applications that want to show\n the answer itself but also the relevant context surrounding the answer.\n\n Answer block is the smallest HTML element that contains the relevant context. However, not all the content\n inside this node is relevant. You can use the `relevant_children_slice` to identify a portion inside this\n block that is relevant to the answer.\n "
}
}
},
"RecordWithFound": {
"title": "RecordWithFound",
"required": [
"product_id"
],
"type": "object",
"properties": {
"product_id": {
"title": "Product Id",
"maxLength": 512,
"type": "string",
"description": "\n The unique identifier for the product.\n ",
"example": "123ABC-S-Black"
}
},
"description": "Product record but support `_found=true / false` field. When _found=false,\nthe product_id will not be available."
},
"Refund": {
"title": "refund",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"refund"
],
"type": "string",
"description": "\nUsed when a user requests a refund of products they bought.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"RemoveFromCart": {
"title": "remove_from_cart",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"remove_from_cart"
],
"type": "string",
"description": "\nUsed when a user removes a product from their shopping cart.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"RemoveFromCollection": {
"title": "remove_from_collection",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"remove_from_collection"
],
"type": "string",
"description": "\nUsed when a user removes a product from their personal collection.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"Search": {
"title": "search",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"search"
],
"type": "string",
"description": "\nUsed to record a search event with the keywords and filters the user used. What a user searches for\nis a very powerful signal about their interests and what they will eventually buy or consume, so it is important\nto capture this information with high fidelity.\n"
},
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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"
},
"search": {
"title": "Search",
"allOf": [
{
"$ref": "#/components/schemas/SearchInformation"
}
],
"description": "\nThe search keywords and filters the user uses. This is only required by `search` interaction.\n"
}
},
"additionalProperties": false
},
"SearchInformation": {
"title": "SearchInformation",
"type": "object",
"properties": {
"keywords": {
"title": "Keywords",
"type": "string",
"description": "\nThe search keywords user use. Search keywords are strong signals to users' interests.\n",
"default": ""
},
"filters": {
"title": "Filters",
"type": "object",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
},
"description": "\nDictionary of filters users apply to the search results in the following format:\n `{\"FIELD\": [\"SELECTION_1\", \"SELECTION_2\"]}`.\n"
}
}
},
"SearchRequest": {
"title": "SearchRequest",
"type": "object",
"properties": {
"engine_id": {
"title": "Engine Id",
"type": "string",
"description": "\nThe engine you want to get results from. When you have more than one engine, you can use this parameter to\nspecify the specific engine you want to get results from. If not specified, the default engine will be used.\n"
},
"user_id": {
"title": "User Id",
"type": "string",
"description": "\nThe user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead.\n"
},
"anonymous_id": {
"title": "Anonymous Id",
"type": "string",
"description": "The anonymous visitor who made the query and for whom Miso will personalize the results. Either\n `user_id` or `anonymous_id` needs to be specified for personalization to work. "
},
"user_hash": {
"title": "User Hash",
"type": "string",
"description": "\nThe hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key).\n`user_hash` is required to prevent unauthorized API access if you are\nmaking API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key).\n\nYou should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your\n[Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server,\nand then let the front-end code send the generated user_hash to Miso APIs to\nverify the identity of the API caller.\n\nAs long as the [Secret API Key](#section/Authentication/Secret%20API%20Key)\n is kept secret, the user_hash prevents a malicious attacker from making unauthorized\nAPI calls or impersonating any of your users.\n\nMiso APIs accept the case-incentive \"hex digest\" of user hash, a sample Python 3 code to generate it on your backend server\nis as follow:\n\n```python\nimport hashlib\nimport hmac\n\nYOUR_MISO_SECRET_API_KEY = \"039c501ac8dfcac91\"\nkey_bytes = YOUR_MISO_SECRET_API_KEY.encode()\nuser_id = \"USER_123\" # or anonymous_id\nuser_id_bytes = user_id.encode()\nuser_hash = hmac.new(\n key_bytes,\n user_id_bytes,\n hashlib.sha256).hexdigest()\n# user_hash is \"7eb04da5e...\"\n```\n\nYou can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e)\n"
},
"user_cohort": {
"title": "User Cohort",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
]
},
"description": "\nThe user cohort you want to cold-start the recommendation with. For example, the following query will make\nrecommendations based on the preferences of the users whose `country=\"United States\"`, and `gender=\"Female\"`\nin the User Profile dataset.\n```\n{\n \"user_cohort\": {\n \"country\": \"United States\",\n \"gender\": \"Female\"\n }\n}\n```\n"
},
"rows": {
"title": "Rows",
"type": "integer",
"description": "Number of search results to return.",
"default": 5
},
"type": {
"title": "Type",
"type": "string",
"description": "\nThe type of products to return. Use this parameter to make the API return only\na certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)).\n\nThis is particularly useful for sites that have multiple types of products:\nFor example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can\nthen use type parameter to limit the recommendation or search results to return only one kind of them.\n\nFor instance, the following query will return only *store* products:\n ```\n{\"type\": \"store\"}\n ```\n\nFor another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*,\nthree kinds\nof products. You can use `type` parameter to limit results to one kind of them. For instance, the following\nquery will limit the results to only *hotels* product:\n ```\n{\"type\": \"hotel\"}\n ```\n"
},
"dedupe_product_group_id": {
"title": "Dedupe Product Group Id",
"type": "boolean",
"description": "\nWhether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`,\nMiso will prevent products with the same `product_group_id` from showing multiple\ntimes in the search or recommendation results.\n\n\nThis is particular useful when one product has multiple variants (for example, different\nsizes, colors, or materials), and you only want to show this product only once in the search or recommendation\nresults. Miso will then return the variant that is most likely to be of the user's interest.\n",
"default": true
},
"additional_interactions": {
"title": "Additional Interactions",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ProductDetailPageView"
},
{
"$ref": "#/components/schemas/Search"
},
{
"$ref": "#/components/schemas/AddToCart"
},
{
"$ref": "#/components/schemas/RemoveFromCart"
},
{
"$ref": "#/components/schemas/Checkout"
},
{
"$ref": "#/components/schemas/Refund"
},
{
"$ref": "#/components/schemas/Subscribe"
},
{
"$ref": "#/components/schemas/Unsubscribe"
},
{
"$ref": "#/components/schemas/AddToCollection"
},
{
"$ref": "#/components/schemas/RemoveFromCollection"
},
{
"$ref": "#/components/schemas/Read"
},
{
"$ref": "#/components/schemas/Watch"
},
{
"$ref": "#/components/schemas/Listen"
},
{
"$ref": "#/components/schemas/Like"
},
{
"$ref": "#/components/schemas/Dislike"
},
{
"$ref": "#/components/schemas/Share"
},
{
"$ref": "#/components/schemas/Rate"
},
{
"$ref": "#/components/schemas/Bookmark"
},
{
"$ref": "#/components/schemas/Complete"
},
{
"$ref": "#/components/schemas/Feedback"
},
{
"$ref": "#/components/schemas/Impression"
},
{
"$ref": "#/components/schemas/ViewableImpression"
},
{
"$ref": "#/components/schemas/Click"
},
{
"$ref": "#/components/schemas/Submit"
},
{
"$ref": "#/components/schemas/HomePageView"
},
{
"$ref": "#/components/schemas/CategoryPageView"
},
{
"$ref": "#/components/schemas/PromoPageView"
},
{
"$ref": "#/components/schemas/ProductImageView"
},
{
"$ref": "#/components/schemas/Custom"
}
]
},
"description": "\nA list of additional interaction records. You can use this fields to simulate user interactions without\nactually writing them to the interaction dataset.\n",
"default": []
},
"fl": {
"title": "Fl",
"type": "array",
"items": {
"type": "string"
},
"description": "\nList of fields to retrieve. For example, the following request retrieves only the `title` field of each product along\nwith the `product_id`, which is always returned.\n\n```\n{\"fl\": [\"title\"]}\n```\n\nYou can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title`\nand any custom attributes under the `attributes` dictionary.\n\n```\n{\"fl\": [\"title\", \"attributes.*\"]}\n```\n\nThe following retrieves all the available fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default).\n```\n{\"fl\": []}\n```\n",
"default": []
},
"exclude": {
"title": "Exclude",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of `product_ids` of products you want to *exclude* from search results."
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nIn certain cases, Miso will take these variables into account when generating results.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
},
"q": {
"title": "Q",
"minLength": 1,
"type": "string",
"description": "\nThe search query the user has entered. Miso will perform full-text search and find any Products\nthat contain every word in this query. You can also set `q=\"*\"` to match all Products, which is commonly used along\nwith Product filtering query `fq` to implement Category Pages.\n\n*(to make a search request, You need to specify either `q` or `advanced_q`)*\n"
},
"advanced_q": {
"title": "Advanced Q",
"minLength": 1,
"type": "string",
"description": "\nLike Google's Advanced Search, the `advanced_q` parameter let you define query beyond simple full-text\nsearch. For one, you can use double-quotes to indicate a phrase search.\n\nFor example, the following query will\nonly match Products that contain the *phrase* \"Toy Story 4\", and will not match Products like \"4 Toy Story\"\n(because the word order is not the same as the given query).\n```\n{\"advanced_q\": \"full_text:\\\"Toy Story 4\\\"\"}\n```\n\nIf you don't want phrase search, you can enclose the search terms with parenthesis to indicate regular full-text query.\nFor example:\n```\n{\"advanced_q\": \"full_text:(Toy Story 4)\"}\n```\n\nYou can also use AND/OR boolean operators to combine multiple full-text queries. For example, the following query will match\nProducts with phrases \"Toy Story 4\" and Products with phrases \"Toy Story 3\", and will not match \"Toy Story 2\" or \"Toy Story 1\":\n```\n{\"advanced_q\":\n\"full_text:\\\"Toy Story 4\\\" OR full_text:\\\"Toy Story 3\\\"\"}\n```\n\nFinally, you can use AND/OR boolean operators to combine full-text search with metadata filtering.\nFor example, the following example will find Products with phrase \"Toy Story\" OR Products which have Tom Hanks as an actor.\n```\n{\"advanced_q\":\n\"full_text:\\\"Toy Story\\\" OR\n custom_attributes.actors:\\\"Tom Hanks\\\"\"}\n```\n\n*(to make a search request, You need to specify either `q` or `advanced_q`)*\n"
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "\nWhen `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s),\nthose boost rules will be matched, regardless if the criteria is met or not.\n\nUseful when want to force trigger specific boost campaign.\n",
"default": [],
"example": [
"tag-1",
"quetag-2"
]
},
"enable_boosting_campaigns": {
"title": "Enable Boosting Campaigns",
"type": "boolean",
"description": "\nWhen set to true, enable user defined boosting campaigns.\n\nBy default boosting campaigns are enabled. But you can explicitly set this to false to disable\nboosting campaigns.\n",
"default": true
},
"include": {
"title": "Include",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of product ids you want to *include* into search results, regardless if main query matches.",
"default": []
},
"language": {
"title": "Language",
"type": "string",
"description": "\nTwo-letter (639-1) language code of the search query. This parameter is useful when you have a multilingual\n product catalog that contains product metadata in different languages.\n If given, the search results will prioritize the products that have that specific language and match the search\n query. Example query:\n```\n{\"language\": \"fr\"}\n```\n\nIf not given, Miso will search against all the languages in the catalog.\n"
},
"like": {
"title": "Like",
"type": "string",
"description": "The text snippet that we want to find products that are similar to it"
},
"category": {
"title": "Category",
"type": "array",
"items": {
"type": "string"
},
"description": "\n`category` parameter limits the search results to a particular category or sub-category.\nThis is particularly suitable for implementing Category Pages where\nyou want to show personalized ranking of Products under a specific category. Other filters, such as `q`,\n`fq`, `boost_fq` will be applied on top of the category filter.\n\nA category is represented by a list of strings that correspond to its category hierarchy.\nFor example, the following query returns Products under `Snacks` category:\n```\n{\n \"q\": \"*\",\n \"category\": [\"Snacks\"]\n}\n```\nAnd the following request returns Products under `Snacks -> Chips` subcategory:\n```\n{\n \"q\": \"*\",\n \"category\": [\"Snacks\", \"Chips\"]\n}\n```\n"
},
"spellcheck": {
"title": "Spellcheck",
"allOf": [
{
"$ref": "#/components/schemas/SpellCheckRequest"
}
],
"description": "Spellcheck configuration",
"default": {
"enable_auto_spelling_correction": true
}
},
"start": {
"title": "Start",
"type": "integer",
"description": "\nSpecifies an offset from which Miso will begin returning results.\n\nThe default value is `0`. Setting the start parameter to some other number, such as 3, causes Miso to skip over the\npreceding products and start from the product identified by the offset.\n",
"default": 0
},
"order_by": {
"title": "Order By",
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderByDefinition"
},
"description": "\nA list of fields that Miso should use to sort the result, instead of Miso's default ranking order.\n\nFor example, the following query returns all the Products (because `q=*`), ranked by the `_personalization_score`\nfirst, and then by the values in the `custom_attributes.promote_score` field in the Product catalog, then the\ndistance between the product and New York city.\n```\n{\n \"q\": \"*\",\n \"order_by\": [\n {\n \"field\": \"_personalization_score\",\n \"tie_breaker\": {\n \"type\": \"relative_difference\",\n \"threshold\": \"0.05\"\n },\n \"order\": \"desc\"\n },\n {\n \"field\": \"custom_attributes.promote_score\",\n \"order\": \"desc\"\n },\n {\n \"field\": \"_geo_distance\",\n \"geo\": {\n \"lat\": 40.711967,\n \"lon\": -74.006076,\n }\n \"order\": \"asc\"\n }\n ]\n}\n```\n",
"default": []
},
"facets": {
"title": "Facets",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/FacetDefinition"
},
{
"type": "string"
}
]
},
"description": "\nSpecifies a list of fields to create facet search against. You can specify `facets` in a string array.\nFor example, the following query return the facet counts for `categories`, `tags`, and `custom_attributes.director`:\n```\n{\n \"facets\": [\n \"categories\",\n \"tags\",\n \"custom_attributes.director\"\n ]\n}\n```\n\nThe response will be like:\n```\n{\n \"facet_counts\": {\n \"facet_fields\": {\n \"categories\": [\n [\n \"Drama\", 20\n ],\n [\n \"Action\", 10\n ], ...\n ],\n \"tags\": [\n [\n \"based on novel or book\", 5\n ],\n [\n \"android\", 4\n ], ...\n ],\n \"custom_attributes.director\": [\n [\n \"Ridley Scott\", 26\n ],\n [\n \"Andrew Abbott\", 1\n ], ...\n }\n }\n```\n\nYou can also specify `facets` with an object array to configure each facet individually.\nFor example, the following query will return 20 most common facet values for `tags`\nand `custom_attributes.director` fields,\nand only the directors whose names start with `Ridley` will be included in the director facet results.\n```\n{\n \"facets\": [\n {\n \"field\": \"tags\",\n \"size\": 20\n },\n {\n \"field\": \"custom_attributes.director\",\n \"size\": 20,\n \"include\": \"Ridley.*\"\n }\n ]\n}\n```\n",
"default": []
},
"facet_filters": {
"title": "Facet Filters",
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/Filter"
},
"description": "\nSpecifies filters to the search results based on users' selections in a faceted search UI.\n\nFor example, assume you have two facets in your faceted search UI: `genres` and `custom_attributes.director`.\nWhen the user selects two options in the `custom_attributes.director` facet, you should send the following query to\nfilter the search results for those two options (i.e. `Ridley Scott` or `Denis Villeneuve`).\n\n```\n{\n \"facets\": [\n {\n \"field\": \"genres\",\n \"size\": 5\n },\n {\n \"field\": \"custom_attributes.director\",\n \"size\": 20\n }\n ],\n \"facet_filters\": {\n \"custom_attributes.director\": {\n \"terms\": [\n \"Ridley Scott\",\n \"Denis Villeneuve\"\n ]\n }\n },\n}\n```\n\nWhile you can use `fq` parameter to achieve the same filtering capability,\nyou should use `facet_filters` to get the correct facet counts.\n\nIn a typical faceted search UI, the facet counts reflect the search result after applying\nfilters from **all but the current facets**. For example, in the query below,\nthe *directors* facet counts\n should reflect the search result after applying the filter from the *genres* facet, i.e. `genres:Sci-Fi`.\n Similarly, *genres* facet counts should reflect the search result after applying the filter from the *directors* facet.\n\n`facet_filters` will make the resulting `facet_counts` follow this *all but except itself* convention, which is rather\n tricky to implement with `fq`.\n```\n \"facets\": [\n {\n \"field\": \"genres\",\n \"size\": 5\n },\n {\n \"field\": \"custom_attributes.director\",\n \"size\": 20\n }\n ],\n \"facet_filters\": {\n \"custom_attributes.director\": {\n \"terms\": [\n \"Ridley Scott\",\n \"Denis Villeneuve\"\n ]\n }\n },\n}\n```\n\n",
"default": {}
},
"anchoring_settings": {
"title": "Anchoring Settings",
"type": "array",
"items": {
"$ref": "#/components/schemas/AnchoringEntry"
},
"description": "\nPromote a product to a position relative to the highest-ranked anchor product.\n\nA common use-case is promoting a private-label good by anchoring it to a name-brand counterpart. When the name-brand good (the anchor) appears in a search result, the private-label good also appears in the result (at a specified distance from the anchor product).\n\nThe `anchoring_settings` object has the following fields:\n* **product_id** - The `product_id` of the product you want to promote.\n* **anchor_ids** - The array of `product_ids` that act as the anchors.\n* **relative_position** *(optional)* - The position that the promoted product will be returned in the search results, relative to the highest-ranked anchor product. For example, setting this parameter to `1` will place the promoted product directly after the anchor product. The default value is `-1`, which will place the promoted product directly before the anchor product.\n* **start_time** *(optional)* - An ISO-8601 timestamp indicating when to start the product anchoring. Ex: `2022-01-29T00:00:00Z`\n* **end_time** *(optional)* - An ISO-8601 timestamp indicating when to end the product anchoring. Ex: `2022-05-31T23:59:59Z`\n\nFor example, if a user searches for \"cookies\", the API request might look like this:\n\n```\nPOST v1/search/search\n{\n \"q\":\"cookies\",\n \"anchoring_settings\": [\n {\n \"product_id\": \"private_label_cookies\",\n \"anchor_ids\": [\n \"name_brand_cookies_1\",\n \"name_brand_cookies_2\"\n ],\n \"relative_position\": -1,\n \"start_time\": \"2022-01-01T00:00:00Z\",\n \"end_time\": \"2022-12-31T23:59:59Z\"\n }\n }\n ]\n}\n```\n",
"default": []
},
"exclude_fields_from_search": {
"title": "Exclude Fields From Search",
"type": "array",
"items": {
"title": " Exclude Fields From Search",
"anyOf": [
{
"const": "title",
"type": "string"
},
{
"const": "subtitle",
"type": "string"
},
{
"const": "description",
"type": "string"
},
{
"const": "short_description",
"type": "string"
},
{
"const": "paragraphs",
"type": "string"
},
{
"const": "headers",
"type": "string"
},
{
"const": "anchors",
"type": "string"
}
]
},
"description": "A list of fields you want to exclude from matching the search keywords. If not specified, all fields will be considered. Curently, only certain fields are supported for exclusion.\n\nFor example, you might exclude the `description` field to improve search precision if the descriptions often contain misleading information.\n\n```json\n{\n exclude_fields_from_search: [\"description\"]\n}\n```\n\nIn this example, the search will match the query against all fields except `description`.\n"
},
"enable_partial_match": {
"title": "Enable Partial Match",
"type": "boolean",
"description": "\nEnable *partial match* to return products that match only *some* of the keywords in a user's search query. By default,\nMiso's Search API only returns products that contain *all* the keywords in the search query (i.e. an AND operator over\nkeywords). This strategy usually leads to highly relevant results. However, when we don't have enough search results to\nreturn to the users, enabling partial match allows the Search API to relax the criteria and return products that match\nonly some of the keywords.\n\nThis strategy is particularly useful to prevent users from seeing an empty search result page and abandoning their\nsearch.\n\nFor example, let's consider the query request below:\n```\n{\n \"query\": \"Toy story 5\",\n \"enable_partial_match\": true\n}\n```\nSince there is no movie called \"Toy story 5\", we have zero products to return by default. However, because we set `enable_partial_match` to `true`, we will return other products that partially match the query:\n```\n{\n\"data\": {\n \"products\": [\n {\n \"title\": \"Toy Story\",\n \"_missing_keywords\": [\"5\"]\n },\n {\n \"title\": \"Toy story 2\",\n \"_missing_keywords\": [\"5\"]\n },\n ...\n ],\n \"total\": 4\n}\n}\n```\nAs you can see from the result above, when we don't have the exact product that the user is looking for, enabling partial match is a helpful strategy to let users know what alternatives are available, and prevent them from seeing an empty search result page.\n",
"default": false
},
"partial_match_mode": {
"title": "Partial Match Mode",
"enum": [
"blended",
"separated"
],
"description": "\nDetermine which partial match mode to enable:\n * **blended** (default): When `partial_match_mode` is `blended`, keyword-matched items and semantically-matched items will\nbe returned in the same, rank-sorted array.\n * **separated**: When `partial_match_mode` is `separated`, keyword-matched items will be returned in the `products` array\nand partially-matched or semantically-matched items will be returned in the `partially_matched_products` array.\n",
"default": "blended"
},
"enable_partial_match_threshold": {
"title": "Enable Partial Match Threshold",
"type": "integer",
"description": "\nIf `partial_match_mode=separated`, you need to provide a value for `enable_partial_match_threshold`.\nThis parameter, which accepts an integer (*n*), creates a condition for Miso’s Search Engine to only provide partially\nmatched results if there are *n* or fewer exact keyword matches. For example, if we set `enable_partial_match_threshold=3`,\npartially matched results will *only* be returned when there are three or fewer exact keyword matches.\n"
},
"enable_semantic_search": {
"title": "Enable Semantic Search",
"type": "boolean",
"description": "\nEnable *semantic search* to return products that are semantically relevant to the search query.\nSemantic search is a powerful tool that further improves the partial match results. It finds products that might not contain\nany of the search keywords, but are highly relevant to users' search intent.\n\nFor example, consider the query: `rubbing alcohol`, which is a household cleaning product. When `enable_semantic_search=true`,\neven if we do not have any products that match `rubbing alcohol`, Miso is still able to return results like the\nfollowing:\n```\n{\n\"data\": {\n \"products\": [],\n \"total\": 0,\n \"partially_matched_products\": [\n {\n \"title\": \"Clorox Disinfecting Wipes Multi-Surface Cleaning\",\n \"_missing_keywords\": [\"rubbing\", \"alcohol\"]\n },\n {\n \"title\": \"Purell Advanced Hand Sanitizer Refreshing Gel\",\n \"_missing_keywords\": [\"rubbing\", \"alcohol\"]\n },\n ...\n ]\n}\n}\n```\nNote that, these two products from Clorox or Purell do not contain any of the search keywords,\nMiso's semantic search functionality, however, is still able to identify them as good matches based on their semantic\nrelevancy to the query `rubbing alcohol`.\n\nSimilarly, consider a single word search query: `aspirin`. Normally, a single-word query will lead to an empty search\npage if we don't have products containing that word. However, when `enable_semantic_search=true`,\neven if we do not directly have `aspirin` in the product catalog, Miso is still able to return results that are highly\nrelevant to users' search intent, such as:\n```\n{\n\"data\": {\n \"products\": [],\n \"total\": 0,\n \"partially_matched_products\": [\n {\n \"title\": \"Advil Pain Reliever and Fever Reducer\",\n \"_missing_keywords\": [\"aspirin\"]\n },\n {\n \"title\": \"Tylenol Extra Strength Caplets\",\n \"_missing_keywords\": [\"aspirin\"]\n },\n ...\n ]\n}\n}\n```\n",
"default": false
},
"semantic_search_threshold": {
"title": "Semantic Search Threshold",
"type": "number",
"description": "\nDetermine the threshold for semantic search. Only the products with a semantic similarity score higher than the\nthreshold will be returned. Setting this too low (e.g. < 0.3) will result in less relevant results being returned.\n",
"default": 0.5
},
"enable_matched_fields": {
"title": "Enable Matched Fields",
"type": "boolean",
"description": "\nDetermine whether to return `_matched_fields` in the search response (default: false).\nIf `enable_matched_fields=true`,\neach returned product will have an `_matched_fields` array that shows which parts of the product catalog match\n the search query.\n\n For example, the following request will return `_matched_fields`:\n```\n{\n \"q\": \"toy story\",\n \"enable_matched_fields\": true\n}\n```\nThe response will be like:\n```\n{\n \"data\": {\n \"products\": [\n {\n \"title\": \"Toy Story\",\n \"_matched_fields\": [\"title\", \"metadata\"]\n },\n ...\n ]\n }\n}\n```\nCurrently, `_matched_fields` only contain three kinds of fields:\n * `title`\n * `description`\n * `metadata`, including all the fields beyond title or description in the product catalog.\n\n",
"default": false
},
"query_product_existence": {
"title": "Query Product Existence",
"allOf": [
{
"$ref": "#/components/schemas/CheckProductExistence"
}
],
"description": "Additionally check if certain products will be in the search result at all (regardless of `start` and `rows` parameters)"
},
"personalization_weight": {
"title": "Personalization Weight",
"maximum": 5.0,
"minimum": 0.0,
"type": "integer",
"description": "Determines how much personalization will affect the search ranking.",
"default": 5
},
"fq": {
"title": "Fq",
"type": "string",
"description": "\n\nDefines a query in Solr syntax that can be used to restrict the superset of\nproducts to return, without influencing the overall ranking. `fq` can enable users to drill down to products\nwith specific features based on different product attributes\n\nFor example, the query below limits the search results to only show products whose size is either `M` or `S` and\nbrand is `Nike`:\n\n```\n{\"fq\": \"size:(\\\"M\\\" OR \\\"S\\\") AND brand:\\\"Nike\\\"\"}\n```\n\nYou can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the\nsearch results to only products whose `designer` attribute is `Calvin Klein`\n\n```\n{\"fq\": \"attributes.designer:\\\"Calvin Klein\\\"\"}\n```\n\n`fq` can also limit search results by numerical range. For example, the following query limits the results to\nproducts that have `rating >= 4`.\n\n```\n{\"fq\": \"rating:[4 TO *]\"}\n```\n"
},
"boost_fq": {
"title": "Boost Fq",
"type": "string",
"description": "\nDefines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to\nspecific *boost positions* (See `boost_positions` parameter below.)\nFor example, the query below will promote all the relevant products whose brand is `Nike` to the top of\nrecommendation list:\n\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\"\n}\n```\n\nFor a slightly more complex example, the query below will promote the Nike products which have also been tagged\nas `ON SALE` to the top of the ranking:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\"\n}\n```\nIt is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert,\nand will not boost a low performance product only because it matches the boosting query.\n\nDepending on your boosting rules, in certain cases, you would like to prevent recommendation results from being\ntoo monotone due to boosting. With Miso, you have two tools to do so.\n\nFirst, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For\nexample, the query below will place boosted products only at the first and fourth places in the ranking\n(positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"boost_positions\": [0, 3]\n}\n```\n\nThe second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to\nmaintain a minimum distance between products that have the same attributes. For example, the following query\nwill place products made by the same brand apart from each other.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"diversification\": {\n \"brand\": {\"minimum_distance\": 1}\n }\n}\n```\n"
},
"boost_positions": {
"title": "Boost Positions",
"type": "array",
"items": {
"type": "integer"
},
"description": "\nDefines a list of 0-based positions you want to place the boosted products at.\n\nFor example, the query below will promote products whose brand is `Nike` as the top and second recommendations:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n}\n```\nIf `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked\nhigher than the rest of the products.\n"
},
"boost_rule_name": {
"title": "Boost Rule Name",
"type": "string",
"description": "Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response"
},
"boost_rules": {
"title": "Boost Rules",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostingFilterBase"
},
"description": "\nDefine a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules`\nparameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different\npositions. For example, the query below will promote products whose brand is `Nike` to the top\nand second results, and products whose brand is `Adidas` to the third and fourth results:\n```\n{\n \"boost_rules\": [\n {\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n },\n {\n \"boost_fq\": \"brand:\\\"Adidas\\\"\",\n \"boost_positions\": [2, 3]\n }\n ]\n}\n```\n",
"default": []
},
"geo": {
"title": "Geo",
"allOf": [
{
"$ref": "#/components/schemas/GeoQuery"
}
],
"description": "\nWhen set, filter result to include only products within certain geographic range from given point will be returned,\nor to boost product within the same range.\n\nProduct should have a field that holds the location of the product, `location` is used by default,\nbut other field can also be used.\n\nDistance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used.\n\nFor example, to limit results to products within 100 miles of New York city:\n```\n{\n \"geo\": {\n \"filter\": [{\n \"lat\": 40.73061,\n \"lon\": -73.93524,\n \"distance\": 100\n }]\n }\n}\n```\n\nTo boost products within 2 kilometers around Alcatraz Island according to `loc` field:\n```\n{\n \"geo\": {\n \"boost\": [{\n \"field\": \"loc\",\n \"lat\": 37.82667,\n \"lon\": -122.42278,\n \"distance\": 2,\n \"distance_unit\": \"km\"\n }]\n }\n}\n```\n"
},
"diversification": {
"title": "Diversification",
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/DiversifyField"
},
"description": "\n\nDefines diversification rules to prevent products with the same attributes (e.g. sneakers made by the same brand\nor books from the same authors) from showing up too close to each other in the results.\n\nFor instance, customers who have purchased many of sneakers from Nike may happen to have recommendations or\nsearch results where all top-5 entries are sneakers made by Nike. Purely considering accuracy, these\nrecommendations appear excellent since the user clearly appreciates Nike sneakers. However,\nsuch results might be considered too \"plain\" by the user, owing to its lack of diversity.\n\n`diversification` parameter allows you to avoid this problem by enforcing a desired *minimum distance* between\nproducts. For example, consider a list of four products whose `brand` are *Nike, Nike, Adidas,* and *PUMA*\nrespectively. The query below will make sure there are at least one different product between two Nike\nproducts, e.g. the diversified ranking may become *Nike, Adidas, Nike,* and *PUMA* :\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 1}}\n}\n```\n\nYou can also increase the minimum_distance to place products further apart. For example, the following query will\nmake sure, for the two Nike products, there are at least *two* other products between them.\nAs a result, the diversified ranking may become *Nike, Adidas, PUMA*, and *Nike*.:\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 2}}\n}\n```\n\nThe diversification algorithm reranks the products on a best-effort basis. For example, for the product list\ndescribed earlier, it is not possible to place two Nike product three places apart from each other. Therefore,\nthe diversified ranking will still remain *Nike, Adidas, PUMA,* and Nike* even if we set `minimum_distance=3`.\n"
}
},
"additionalProperties": false
},
"SearchResponse": {
"title": "SearchResponse",
"required": [
"data"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"default": "success"
},
"data": {
"$ref": "#/components/schemas/SearchResponseBody"
}
}
},
"SearchResponseBody": {
"title": "SearchResponseBody",
"required": [
"products",
"total",
"start",
"spellcheck"
],
"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": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"format": "uuid",
"default": "00000000-0000-0000-0000-000000000000",
"example": "123e4567-e89b-12d3-a456-426614174000"
},
"products": {
"title": "Products",
"type": "array",
"items": {
"$ref": "#/components/schemas/PartialMatchedRecord"
},
"description": "The search results."
},
"total": {
"title": "Total",
"type": "integer",
"description": "Total number of search hits.",
"example": 1000
},
"start": {
"title": "Start",
"type": "integer",
"description": "Starting offset of the search results.",
"example": 0
},
"spellcheck": {
"title": "Spellcheck",
"allOf": [
{
"$ref": "#/components/schemas/SpellCheckResponse"
}
],
"description": "Spellcheck results. You can use the information in this object to prompt users with the correct spelling."
},
"product_existence": {
"title": "Product Existence",
"type": "object",
"additionalProperties": {
"type": "boolean"
},
"description": "Product existence query result"
},
"partially_matched_products": {
"title": "Partially Matched Products",
"type": "array",
"items": {
"$ref": "#/components/schemas/PartialMatchedRecord"
},
"description": "The search results that only partially match the search query."
},
"facet_counts": {
"title": "Facet Counts",
"allOf": [
{
"$ref": "#/components/schemas/FacetCounts"
}
],
"description": "Facet counts",
"default": {}
},
"custom_assets": {
"title": "Custom Assets",
"type": "array",
"items": {
"type": "object"
},
"description": "Custom JSON assets uploaded in Dojo.",
"default": []
},
"boosting_rules": {
"title": "Boosting Rules",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/BoostingFilterBase"
},
{
"$ref": "#/components/schemas/GeoDistanceQueryBoost"
}
]
},
"description": "Boosting rules that are applied to the search results.",
"default": []
},
"filtering_rule": {
"title": "Filtering Rule",
"type": "string",
"description": "Filter query that is applied to the search results."
}
}
},
"SendExperimentResponse": {
"title": "SendExperimentResponse",
"required": [
"took",
"in_experiment",
"variant"
],
"type": "object",
"properties": {
"took": {
"title": "Took",
"type": "integer",
"description": "The amount of time (in milliseconds) Miso took to answer this request.",
"example": 50
},
"in_experiment": {
"title": "In Experiment",
"type": "boolean",
"description": "To show whether the experiment is active or not."
},
"variant": {
"$ref": "#/components/schemas/VariantObject"
}
}
},
"Share": {
"title": "share",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"share"
],
"type": "string",
"description": "\nUsed when a user shares a product or piece of content.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"SorvnAffData": {
"title": "SorvnAffData",
"required": [
"products"
],
"type": "object",
"properties": {
"meta": {
"title": "Meta",
"type": "object",
"description": "The meta data for the affiliation.",
"default": {}
},
"products": {
"title": "Products",
"type": "array",
"items": {
"type": "object"
},
"description": "The list of affiliation products."
}
}
},
"SpellCheckRequest": {
"title": "SpellCheckRequest",
"type": "object",
"properties": {
"enable_auto_spelling_correction": {
"title": "Enable Auto Spelling Correction",
"type": "boolean",
"description": "\nThis parameter controls whether to automatically correct a misspell search query.\nIf set to `true`, when Miso detects spelling errors, the search results will be based on the\n **corrected** spelling suggested by Miso.\n\nYou call tell if Miso made any correction to the search query by checking the\n`spellcheck.auto_spelling_correction` field in the\nAPI response. When this field is `true`, the search results are based on the suggested spelling\nas opposed to the users' original query.\n\nYou can opt-out the spelling correction by setting this parameter to `false`. In such cases,\nMiso will still detect spelling errors,\nbut the search results will be always based on users' original spelling.\n",
"default": true
}
}
},
"SpellCheckResponse": {
"title": "SpellCheckResponse",
"required": [
"spelling_errors",
"auto_spelling_correction",
"original_query",
"original_query_with_markups",
"corrected_query",
"corrected_query_with_markups"
],
"type": "object",
"properties": {
"spelling_errors": {
"title": "Spelling Errors",
"type": "boolean",
"description": "Whether Miso detects any spelling errors."
},
"auto_spelling_correction": {
"title": "Auto Spelling Correction",
"type": "boolean",
"description": "Whether Miso has automatically corrected the misspelled search query. When this field is `true`, the search result is based on the corrected spelling in the `corrected_query` field instead of users' original search query."
},
"original_query": {
"title": "Original Query",
"type": "string",
"description": "Original query string",
"example": "what is pythn"
},
"original_query_with_markups": {
"title": "Original Query With Markups",
"type": "string",
"description": "Original query with the spelling errors (if any) surrounded by the tags",
"example": "what is pythn"
},
"corrected_query": {
"title": "Corrected Query",
"type": "string",
"description": "The corrected spelling suggested by Miso. If no spelling error is detected, this will be the same as `original_query`",
"example": "what is python"
},
"corrected_query_with_markups": {
"title": "Corrected Query With Markups",
"type": "string",
"description": "The corrected spelling suggested by Miso where the revised tokens are surrounded by the tags.",
"example": "what is python"
}
}
},
"Submit": {
"title": "submit",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"submit"
],
"type": "string",
"description": "\nUsed when a user submits a form or a survey.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"Subscribe": {
"title": "subscribe",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"subscribe"
],
"type": "string",
"description": "\nUsed when a user subscribes a product, for example to receive alerts when the product comes back in stock or if the price drops.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"TaskId": {
"title": "TaskId",
"required": [
"task_id"
],
"type": "object",
"properties": {
"task_id": {
"title": "Task Id",
"type": "string"
}
}
},
"TieBreakDefinition": {
"title": "TieBreakDefinition",
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"relative_difference"
],
"default": "relative_difference"
},
"threshold": {
"title": "Threshold",
"type": "number",
"default": 0.0
}
}
},
"TitleCompletion": {
"title": "TitleCompletion",
"required": [
"text",
"text_with_markups",
"text_with_inverted_markups",
"product"
],
"type": "object",
"properties": {
"text": {
"title": "Text",
"minLength": 1,
"type": "string",
"example": "Japanese Shiba Inu Dog Eating Miso Soup T-Shirt"
},
"text_with_markups": {
"title": "Text With Markups",
"minLength": 1,
"type": "string",
"example": "Japanese Shiba Inu Dog Eating Miso Soup T-Shirt"
},
"text_with_inverted_markups": {
"title": "Text With Inverted Markups",
"minLength": 1,
"type": "string",
"example": "Japanese Shiba Inu Dog Eating Miso Soup T-Shirt"
},
"product": {
"title": "Product",
"allOf": [
{
"$ref": "#/components/schemas/Record"
}
],
"example": {
"product_id": "123ABC-S-Black"
}
}
},
"description": "title completion additionally has the `product` the title belongs to."
},
"TrendRecResponse": {
"title": "TrendRecResponse",
"required": [
"data"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"default": "success"
},
"data": {
"$ref": "#/components/schemas/TrendResponseBody"
}
}
},
"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": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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."
}
}
},
"Unsubscribe": {
"title": "unsubscribe",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"unsubscribe"
],
"type": "string",
"description": "\nUsed when a user unsubscribes a product, for example to stop receiving alerts when the product comes back in stock or if the price drops.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"UserBulkDeleteIn": {
"title": "UserBulkDeleteIn",
"required": [
"data"
],
"type": "object",
"properties": {
"data": {
"$ref": "#/components/schemas/UserIdList"
}
}
},
"UserBulkIn": {
"title": "UserBulkIn",
"required": [
"data"
],
"type": "object",
"properties": {
"data": {
"title": "Data",
"type": "array",
"items": {
"$ref": "#/components/schemas/UserRecord"
}
}
}
},
"UserIdList": {
"title": "UserIdList",
"required": [
"user_ids"
],
"type": "object",
"properties": {
"user_ids": {
"title": "User Ids",
"type": "array",
"items": {
"type": "string"
}
}
}
},
"UserReadOut": {
"title": "UserReadOut",
"required": [
"message",
"data"
],
"type": "object",
"properties": {
"message": {
"title": "Message",
"type": "string",
"description": "Human-readable message",
"example": "success"
},
"data": {
"$ref": "#/components/schemas/UserRecord"
}
}
},
"UserRecord": {
"title": "UserRecord",
"required": [
"user_id"
],
"type": "object",
"properties": {
"user_id": {
"title": "User Id",
"maxLength": 512,
"minLength": 1,
"type": "string",
"description": "\nUnique identifier for a user who has signed in. `user_id` can be in any format (e.g. users' email, internal user\nUUID or serial ID). The only restriction is that the first character must not be an underline `_`. Miso will use \nthis id to cross-reference your User records with your Interaction records.\n",
"example": "user_1234"
},
"created_at": {
"title": "Created At",
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string",
"format": "date"
}
],
"description": "\nThe date the user’s account was created as an ISO-8601 date or datetime string. \n"
},
"updated_at": {
"title": "Updated At",
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string",
"format": "date"
}
],
"description": "\nThe date the user’s account was updated as an ISO-8601 date or datetime string. \n"
},
"name": {
"title": "Name",
"type": "string",
"description": "The user's full name.",
"example": "John Doe"
},
"profile_image": {
"title": "Profile Image",
"maxLength": 65536,
"minLength": 1,
"type": "string",
"description": "URL to the profile image of the user.",
"format": "uri"
},
"age": {
"title": "Age",
"type": "integer",
"description": "Age of the user. We will internally convert it to year of birth.",
"example": 33
},
"gender": {
"title": "Gender",
"type": "string",
"description": "The user's gender.",
"example": "M"
},
"city": {
"title": "City",
"type": "string",
"description": "City or zipcode the user is based in.",
"example": "Mountain View"
},
"state": {
"title": "State",
"type": "string",
"description": "State the user is based in.",
"example": "California"
},
"country": {
"title": "Country",
"type": "string",
"description": "Country the user is based in.",
"example": "US"
},
"group_id": {
"title": "Group Id",
"type": "string",
"description": "\nGroup or Account ID from your CRM. This is useful in B2B scenarios. For example, you can use `group_id` to \nassociate a user with their company or account. We will use this information to infer the user's interests and \nfine-tune their personalization and search results. For example, users from the same group might have similar \ninterests on the site, and we can improve their user experience accordingly\n",
"example": "Northwind Corp"
},
"description": {
"title": "Description",
"type": "string",
"description": "\nText description of the user. This can be the user's own bio or the internal notes about the user. If available,\nMiso will analyze this description to better profile a user. \n",
"example": "Engineer from Northwind Corp"
},
"custom_attributes": {
"title": "Custom Attributes",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "boolean"
}
]
}
}
}
]
},
"description": "\nDictionary of custom attributes about the user. As with the [Product API](#operation/content_write_api_v1_products_post\n), you can specify attributes specific to your business in a `{\"KEY\" : VALUE}` format, where `KEY` must be a string, and\n `VALUE` can be:\n* a `string` or `an array of strings`\n* a `number` or `an array of numbers`\n* an `array of objects`\n* a `bool`\n* `null` \n\n* Example:\n```\n{\n \"custom_attributes\": {\n \"acquisition_channel\": \"Facebook Campaign 2020\",\n \"declared_interests\": [\"Drama\", \"Romance\"]\n }\n}\n```\nThese custom attributes types must be consistent across all User records in your data set. \nRecords with inconsistent types will fail to be inserted.\n",
"example": {
"acquisition_channel": "Facebook Campaign 2020",
"declared_interests": [
"Drama",
"Romance"
]
}
}
},
"additionalProperties": false
},
"UserToAttributes": {
"title": "UserToAttributes",
"required": [
"field"
],
"type": "object",
"properties": {
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "\nWhen `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s),\nthose boost rules will be matched, regardless if the criteria is met or not.\n\nUseful when want to force trigger specific boost campaign.\n",
"default": [],
"example": [
"tag-1",
"quetag-2"
]
},
"field": {
"title": "Field",
"type": "string",
"description": "\n\nThe attribute you want to make recommendations for. For example, the following\nquery will recommend values from the `brand` field that Miso thinks the user will be interested in:\n\n```\n{\"field\": \"brand\"}\n```\n\nThis API also works for custom attributes you define. For example,\nif you provide a `designer` custom attribute, then, you can make `designer` recommendations with the following query.\n```\n{\"field\": \"custom_attributes.designer\"}\n```\n"
},
"boost_attributes": {
"title": "Boost Attributes",
"type": "array",
"items": {
"type": "string"
},
"description": "\n\nThe attributes to boost to the top of the recommendations\n\n",
"default": []
},
"exclude_attributes": {
"title": "Exclude Attributes",
"type": "array",
"items": {
"type": "string"
},
"description": "\n\nThe attributes to remove from the recommendations\n\n",
"default": []
},
"rows": {
"title": "Rows",
"type": "integer",
"description": "Number of product recommendations to return",
"default": 5
},
"products_per_attribute": {
"title": "Products Per Attribute",
"type": "integer",
"description": "\nNumber of personalized product recommendations to make for **each** recommended attribute. For example, the following\nquery will return 5 products for each *brand* we recommend:\n```\n{\n \"field\": \"brand\",\n \"products_per_attribute\": 2\n}\n```\n\nNote that a large number of `products_per_attribute` will increase latency slightly because we need to\nperform more computation for each of the recommended attributes. If you only need attribute\nrecommendations, you can set\n`products_per_attribute=0` to reduce latency.\n",
"default": 2
},
"engine_id": {
"title": "Engine Id",
"type": "string",
"description": "\nThe engine you want to get results from. When you have more than one engine, you can use this parameter to\nspecify the specific engine you want to get results from. If not specified, the default engine will be used.\n"
},
"user_id": {
"title": "User Id",
"type": "string",
"description": "\nThe user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead.\n"
},
"anonymous_id": {
"title": "Anonymous Id",
"type": "string",
"description": "The anonymous visitor who made the query and for whom Miso will personalize the results. Either\n `user_id` or `anonymous_id` needs to be specified for personalization to work. "
},
"user_hash": {
"title": "User Hash",
"type": "string",
"description": "\nThe hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key).\n`user_hash` is required to prevent unauthorized API access if you are\nmaking API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key).\n\nYou should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your\n[Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server,\nand then let the front-end code send the generated user_hash to Miso APIs to\nverify the identity of the API caller.\n\nAs long as the [Secret API Key](#section/Authentication/Secret%20API%20Key)\n is kept secret, the user_hash prevents a malicious attacker from making unauthorized\nAPI calls or impersonating any of your users.\n\nMiso APIs accept the case-incentive \"hex digest\" of user hash, a sample Python 3 code to generate it on your backend server\nis as follow:\n\n```python\nimport hashlib\nimport hmac\n\nYOUR_MISO_SECRET_API_KEY = \"039c501ac8dfcac91\"\nkey_bytes = YOUR_MISO_SECRET_API_KEY.encode()\nuser_id = \"USER_123\" # or anonymous_id\nuser_id_bytes = user_id.encode()\nuser_hash = hmac.new(\n key_bytes,\n user_id_bytes,\n hashlib.sha256).hexdigest()\n# user_hash is \"7eb04da5e...\"\n```\n\nYou can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e)\n"
},
"user_cohort": {
"title": "User Cohort",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
]
},
"description": "\nThe user cohort you want to cold-start the recommendation with. For example, the following query will make\nrecommendations based on the preferences of the users whose `country=\"United States\"`, and `gender=\"Female\"`\nin the User Profile dataset.\n```\n{\n \"user_cohort\": {\n \"country\": \"United States\",\n \"gender\": \"Female\"\n }\n}\n```\n"
},
"type": {
"title": "Type",
"type": "string",
"description": "\nThe type of products to return. Use this parameter to make the API return only\na certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)).\n\nThis is particularly useful for sites that have multiple types of products:\nFor example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can\nthen use type parameter to limit the recommendation or search results to return only one kind of them.\n\nFor instance, the following query will return only *store* products:\n ```\n{\"type\": \"store\"}\n ```\n\nFor another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*,\nthree kinds\nof products. You can use `type` parameter to limit results to one kind of them. For instance, the following\nquery will limit the results to only *hotels* product:\n ```\n{\"type\": \"hotel\"}\n ```\n"
},
"dedupe_product_group_id": {
"title": "Dedupe Product Group Id",
"type": "boolean",
"description": "\nWhether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`,\nMiso will prevent products with the same `product_group_id` from showing multiple\ntimes in the search or recommendation results.\n\n\nThis is particular useful when one product has multiple variants (for example, different\nsizes, colors, or materials), and you only want to show this product only once in the search or recommendation\nresults. Miso will then return the variant that is most likely to be of the user's interest.\n",
"default": true
},
"additional_interactions": {
"title": "Additional Interactions",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ProductDetailPageView"
},
{
"$ref": "#/components/schemas/Search"
},
{
"$ref": "#/components/schemas/AddToCart"
},
{
"$ref": "#/components/schemas/RemoveFromCart"
},
{
"$ref": "#/components/schemas/Checkout"
},
{
"$ref": "#/components/schemas/Refund"
},
{
"$ref": "#/components/schemas/Subscribe"
},
{
"$ref": "#/components/schemas/Unsubscribe"
},
{
"$ref": "#/components/schemas/AddToCollection"
},
{
"$ref": "#/components/schemas/RemoveFromCollection"
},
{
"$ref": "#/components/schemas/Read"
},
{
"$ref": "#/components/schemas/Watch"
},
{
"$ref": "#/components/schemas/Listen"
},
{
"$ref": "#/components/schemas/Like"
},
{
"$ref": "#/components/schemas/Dislike"
},
{
"$ref": "#/components/schemas/Share"
},
{
"$ref": "#/components/schemas/Rate"
},
{
"$ref": "#/components/schemas/Bookmark"
},
{
"$ref": "#/components/schemas/Complete"
},
{
"$ref": "#/components/schemas/Feedback"
},
{
"$ref": "#/components/schemas/Impression"
},
{
"$ref": "#/components/schemas/ViewableImpression"
},
{
"$ref": "#/components/schemas/Click"
},
{
"$ref": "#/components/schemas/Submit"
},
{
"$ref": "#/components/schemas/HomePageView"
},
{
"$ref": "#/components/schemas/CategoryPageView"
},
{
"$ref": "#/components/schemas/PromoPageView"
},
{
"$ref": "#/components/schemas/ProductImageView"
},
{
"$ref": "#/components/schemas/Custom"
}
]
},
"description": "\nA list of additional interaction records. You can use this fields to simulate user interactions without\nactually writing them to the interaction dataset.\n",
"default": []
},
"fl": {
"title": "Fl",
"type": "array",
"items": {
"type": "string"
},
"description": "\nList of fields to retrieve. For example, the following request retrieves only the `title` field of each product along\nwith the `product_id`, which is always returned.\n\n```\n{\"fl\": [\"title\"]}\n```\n\nYou can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title`\nand any custom attributes under the `attributes` dictionary.\n\n```\n{\"fl\": [\"title\", \"attributes.*\"]}\n```\n\nThe following retrieves all the available fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default).\n```\n{\"fl\": []}\n```\n",
"default": []
},
"exclude": {
"title": "Exclude",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of `product_ids` of products you want to *exclude* from search results."
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nIn certain cases, Miso will take these variables into account when generating results.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
},
"fq": {
"title": "Fq",
"type": "string",
"description": "\n\nDefines a query in Solr syntax that can be used to restrict the superset of\nproducts to return, without influencing the overall ranking. `fq` can enable users to drill down to products\nwith specific features based on different product attributes\n\nFor example, the query below limits the search results to only show products whose size is either `M` or `S` and\nbrand is `Nike`:\n\n```\n{\"fq\": \"size:(\\\"M\\\" OR \\\"S\\\") AND brand:\\\"Nike\\\"\"}\n```\n\nYou can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the\nsearch results to only products whose `designer` attribute is `Calvin Klein`\n\n```\n{\"fq\": \"attributes.designer:\\\"Calvin Klein\\\"\"}\n```\n\n`fq` can also limit search results by numerical range. For example, the following query limits the results to\nproducts that have `rating >= 4`.\n\n```\n{\"fq\": \"rating:[4 TO *]\"}\n```\n"
},
"boost_fq": {
"title": "Boost Fq",
"type": "string",
"description": "\nDefines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to\nspecific *boost positions* (See `boost_positions` parameter below.)\nFor example, the query below will promote all the relevant products whose brand is `Nike` to the top of\nrecommendation list:\n\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\"\n}\n```\n\nFor a slightly more complex example, the query below will promote the Nike products which have also been tagged\nas `ON SALE` to the top of the ranking:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\"\n}\n```\nIt is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert,\nand will not boost a low performance product only because it matches the boosting query.\n\nDepending on your boosting rules, in certain cases, you would like to prevent recommendation results from being\ntoo monotone due to boosting. With Miso, you have two tools to do so.\n\nFirst, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For\nexample, the query below will place boosted products only at the first and fourth places in the ranking\n(positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"boost_positions\": [0, 3]\n}\n```\n\nThe second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to\nmaintain a minimum distance between products that have the same attributes. For example, the following query\nwill place products made by the same brand apart from each other.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"diversification\": {\n \"brand\": {\"minimum_distance\": 1}\n }\n}\n```\n"
},
"boost_positions": {
"title": "Boost Positions",
"type": "array",
"items": {
"type": "integer"
},
"description": "\nDefines a list of 0-based positions you want to place the boosted products at.\n\nFor example, the query below will promote products whose brand is `Nike` as the top and second recommendations:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n}\n```\nIf `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked\nhigher than the rest of the products.\n"
},
"boost_rule_name": {
"title": "Boost Rule Name",
"type": "string",
"description": "Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response"
},
"boost_rules": {
"title": "Boost Rules",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostingFilterBase"
},
"description": "\nDefine a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules`\nparameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different\npositions. For example, the query below will promote products whose brand is `Nike` to the top\nand second results, and products whose brand is `Adidas` to the third and fourth results:\n```\n{\n \"boost_rules\": [\n {\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n },\n {\n \"boost_fq\": \"brand:\\\"Adidas\\\"\",\n \"boost_positions\": [2, 3]\n }\n ]\n}\n```\n",
"default": []
},
"geo": {
"title": "Geo",
"allOf": [
{
"$ref": "#/components/schemas/GeoQuery"
}
],
"description": "\nWhen set, filter result to include only products within certain geographic range from given point will be returned,\nor to boost product within the same range.\n\nProduct should have a field that holds the location of the product, `location` is used by default,\nbut other field can also be used.\n\nDistance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used.\n\nFor example, to limit results to products within 100 miles of New York city:\n```\n{\n \"geo\": {\n \"filter\": [{\n \"lat\": 40.73061,\n \"lon\": -73.93524,\n \"distance\": 100\n }]\n }\n}\n```\n\nTo boost products within 2 kilometers around Alcatraz Island according to `loc` field:\n```\n{\n \"geo\": {\n \"boost\": [{\n \"field\": \"loc\",\n \"lat\": 37.82667,\n \"lon\": -122.42278,\n \"distance\": 2,\n \"distance_unit\": \"km\"\n }]\n }\n}\n```\n"
}
},
"additionalProperties": false,
"description": "User to attributes recommendations. Given a user, recommend\nproduct attributes the user will be interested in as well as products in those attributes"
},
"UserToCategories": {
"title": "UserToCategories",
"type": "object",
"properties": {
"engine_id": {
"title": "Engine Id",
"type": "string",
"description": "\nThe engine you want to get results from. When you have more than one engine, you can use this parameter to\nspecify the specific engine you want to get results from. If not specified, the default engine will be used.\n"
},
"user_id": {
"title": "User Id",
"type": "string",
"description": "\nThe user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead.\n"
},
"anonymous_id": {
"title": "Anonymous Id",
"type": "string",
"description": "The anonymous visitor who made the query and for whom Miso will personalize the results. Either\n `user_id` or `anonymous_id` needs to be specified for personalization to work. "
},
"user_hash": {
"title": "User Hash",
"type": "string",
"description": "\nThe hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key).\n`user_hash` is required to prevent unauthorized API access if you are\nmaking API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key).\n\nYou should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your\n[Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server,\nand then let the front-end code send the generated user_hash to Miso APIs to\nverify the identity of the API caller.\n\nAs long as the [Secret API Key](#section/Authentication/Secret%20API%20Key)\n is kept secret, the user_hash prevents a malicious attacker from making unauthorized\nAPI calls or impersonating any of your users.\n\nMiso APIs accept the case-incentive \"hex digest\" of user hash, a sample Python 3 code to generate it on your backend server\nis as follow:\n\n```python\nimport hashlib\nimport hmac\n\nYOUR_MISO_SECRET_API_KEY = \"039c501ac8dfcac91\"\nkey_bytes = YOUR_MISO_SECRET_API_KEY.encode()\nuser_id = \"USER_123\" # or anonymous_id\nuser_id_bytes = user_id.encode()\nuser_hash = hmac.new(\n key_bytes,\n user_id_bytes,\n hashlib.sha256).hexdigest()\n# user_hash is \"7eb04da5e...\"\n```\n\nYou can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e)\n"
},
"user_cohort": {
"title": "User Cohort",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
]
},
"description": "\nThe user cohort you want to cold-start the recommendation with. For example, the following query will make\nrecommendations based on the preferences of the users whose `country=\"United States\"`, and `gender=\"Female\"`\nin the User Profile dataset.\n```\n{\n \"user_cohort\": {\n \"country\": \"United States\",\n \"gender\": \"Female\"\n }\n}\n```\n"
},
"rows": {
"title": "Rows",
"type": "integer",
"description": "Number of recommended categories to return",
"default": 5
},
"type": {
"title": "Type",
"type": "string",
"description": "\nThe type of products to return. Use this parameter to make the API return only\na certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)).\n\nThis is particularly useful for sites that have multiple types of products:\nFor example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can\nthen use type parameter to limit the recommendation or search results to return only one kind of them.\n\nFor instance, the following query will return only *store* products:\n ```\n{\"type\": \"store\"}\n ```\n\nFor another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*,\nthree kinds\nof products. You can use `type` parameter to limit results to one kind of them. For instance, the following\nquery will limit the results to only *hotels* product:\n ```\n{\"type\": \"hotel\"}\n ```\n"
},
"dedupe_product_group_id": {
"title": "Dedupe Product Group Id",
"type": "boolean",
"description": "\nWhether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`,\nMiso will prevent products with the same `product_group_id` from showing multiple\ntimes in the search or recommendation results.\n\n\nThis is particular useful when one product has multiple variants (for example, different\nsizes, colors, or materials), and you only want to show this product only once in the search or recommendation\nresults. Miso will then return the variant that is most likely to be of the user's interest.\n",
"default": true
},
"additional_interactions": {
"title": "Additional Interactions",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ProductDetailPageView"
},
{
"$ref": "#/components/schemas/Search"
},
{
"$ref": "#/components/schemas/AddToCart"
},
{
"$ref": "#/components/schemas/RemoveFromCart"
},
{
"$ref": "#/components/schemas/Checkout"
},
{
"$ref": "#/components/schemas/Refund"
},
{
"$ref": "#/components/schemas/Subscribe"
},
{
"$ref": "#/components/schemas/Unsubscribe"
},
{
"$ref": "#/components/schemas/AddToCollection"
},
{
"$ref": "#/components/schemas/RemoveFromCollection"
},
{
"$ref": "#/components/schemas/Read"
},
{
"$ref": "#/components/schemas/Watch"
},
{
"$ref": "#/components/schemas/Listen"
},
{
"$ref": "#/components/schemas/Like"
},
{
"$ref": "#/components/schemas/Dislike"
},
{
"$ref": "#/components/schemas/Share"
},
{
"$ref": "#/components/schemas/Rate"
},
{
"$ref": "#/components/schemas/Bookmark"
},
{
"$ref": "#/components/schemas/Complete"
},
{
"$ref": "#/components/schemas/Feedback"
},
{
"$ref": "#/components/schemas/Impression"
},
{
"$ref": "#/components/schemas/ViewableImpression"
},
{
"$ref": "#/components/schemas/Click"
},
{
"$ref": "#/components/schemas/Submit"
},
{
"$ref": "#/components/schemas/HomePageView"
},
{
"$ref": "#/components/schemas/CategoryPageView"
},
{
"$ref": "#/components/schemas/PromoPageView"
},
{
"$ref": "#/components/schemas/ProductImageView"
},
{
"$ref": "#/components/schemas/Custom"
}
]
},
"description": "\nA list of additional interaction records. You can use this fields to simulate user interactions without\nactually writing them to the interaction dataset.\n",
"default": []
},
"fl": {
"title": "Fl",
"type": "array",
"items": {
"type": "string"
},
"description": "\nList of fields to retrieve. For example, the following request retrieves only the `title` field of each product along\nwith the `product_id`, which is always returned.\n\n```\n{\"fl\": [\"title\"]}\n```\n\nYou can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title`\nand any custom attributes under the `attributes` dictionary.\n\n```\n{\"fl\": [\"title\", \"attributes.*\"]}\n```\n\nThe following retrieves all the available fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default).\n```\n{\"fl\": []}\n```\n",
"default": []
},
"exclude": {
"title": "Exclude",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of `product_ids` of products you want to *exclude* from search results."
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nIn certain cases, Miso will take these variables into account when generating results.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "\nWhen `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s),\nthose boost rules will be matched, regardless if the criteria is met or not.\n\nUseful when want to force trigger specific boost campaign.\n",
"default": [],
"example": [
"tag-1",
"quetag-2"
]
},
"products_per_category": {
"title": "Products Per Category",
"type": "integer",
"description": "\n\nNumber of products to return for **each** category. For example, the following\nquery will return 5 products for each category we recommend:\n```\n{\"products\": 5}\n```\nNote that, a large number of `products_per_category` (say >= 20) will increase query latency (up to around 200ms)\nbecause we need to perform more computation for each of the recommended categories. If you\nonly need category recommendations, you should set `products_per_category` to 0 to reduce latency.",
"default": 5
},
"root_category": {
"title": "Root Category",
"type": "array",
"items": {
"type": "string"
},
"description": "\nIf `root_category` is specified, we will only recommend categories that are direct children of each of the root\ncategory. For example, the following query will recommend the products of category that is under `[\"Clothes\"]` category:\n```\n{\"root_category\": [\"Clothes\"]}\n```\nFor another example, the following query will recommend the products of category that is under `[\"Clothes\", \"Dresses\"]` category\n```\n{\"root_category\": [\"Clothes\", \"Dresses\"]}\n```\nIf `root_category` is not specified, we will recommend the *top level* categories. ",
"default": []
},
"fq": {
"title": "Fq",
"type": "string",
"description": "\n\nDefines a query in Solr syntax that can be used to restrict the superset of\nproducts to return, without influencing the overall ranking. `fq` can enable users to drill down to products\nwith specific features based on different product attributes\n\nFor example, the query below limits the search results to only show products whose size is either `M` or `S` and\nbrand is `Nike`:\n\n```\n{\"fq\": \"size:(\\\"M\\\" OR \\\"S\\\") AND brand:\\\"Nike\\\"\"}\n```\n\nYou can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the\nsearch results to only products whose `designer` attribute is `Calvin Klein`\n\n```\n{\"fq\": \"attributes.designer:\\\"Calvin Klein\\\"\"}\n```\n\n`fq` can also limit search results by numerical range. For example, the following query limits the results to\nproducts that have `rating >= 4`.\n\n```\n{\"fq\": \"rating:[4 TO *]\"}\n```\n"
},
"boost_fq": {
"title": "Boost Fq",
"type": "string",
"description": "\nDefines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to\nspecific *boost positions* (See `boost_positions` parameter below.)\nFor example, the query below will promote all the relevant products whose brand is `Nike` to the top of\nrecommendation list:\n\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\"\n}\n```\n\nFor a slightly more complex example, the query below will promote the Nike products which have also been tagged\nas `ON SALE` to the top of the ranking:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\"\n}\n```\nIt is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert,\nand will not boost a low performance product only because it matches the boosting query.\n\nDepending on your boosting rules, in certain cases, you would like to prevent recommendation results from being\ntoo monotone due to boosting. With Miso, you have two tools to do so.\n\nFirst, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For\nexample, the query below will place boosted products only at the first and fourth places in the ranking\n(positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"boost_positions\": [0, 3]\n}\n```\n\nThe second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to\nmaintain a minimum distance between products that have the same attributes. For example, the following query\nwill place products made by the same brand apart from each other.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"diversification\": {\n \"brand\": {\"minimum_distance\": 1}\n }\n}\n```\n"
},
"boost_positions": {
"title": "Boost Positions",
"type": "array",
"items": {
"type": "integer"
},
"description": "\nDefines a list of 0-based positions you want to place the boosted products at.\n\nFor example, the query below will promote products whose brand is `Nike` as the top and second recommendations:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n}\n```\nIf `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked\nhigher than the rest of the products.\n"
},
"boost_rule_name": {
"title": "Boost Rule Name",
"type": "string",
"description": "Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response"
},
"boost_rules": {
"title": "Boost Rules",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostingFilterBase"
},
"description": "\nDefine a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules`\nparameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different\npositions. For example, the query below will promote products whose brand is `Nike` to the top\nand second results, and products whose brand is `Adidas` to the third and fourth results:\n```\n{\n \"boost_rules\": [\n {\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n },\n {\n \"boost_fq\": \"brand:\\\"Adidas\\\"\",\n \"boost_positions\": [2, 3]\n }\n ]\n}\n```\n",
"default": []
},
"geo": {
"title": "Geo",
"allOf": [
{
"$ref": "#/components/schemas/GeoQuery"
}
],
"description": "\nWhen set, filter result to include only products within certain geographic range from given point will be returned,\nor to boost product within the same range.\n\nProduct should have a field that holds the location of the product, `location` is used by default,\nbut other field can also be used.\n\nDistance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used.\n\nFor example, to limit results to products within 100 miles of New York city:\n```\n{\n \"geo\": {\n \"filter\": [{\n \"lat\": 40.73061,\n \"lon\": -73.93524,\n \"distance\": 100\n }]\n }\n}\n```\n\nTo boost products within 2 kilometers around Alcatraz Island according to `loc` field:\n```\n{\n \"geo\": {\n \"boost\": [{\n \"field\": \"loc\",\n \"lat\": 37.82667,\n \"lon\": -122.42278,\n \"distance\": 2,\n \"distance_unit\": \"km\"\n }]\n }\n}\n```\n"
}
},
"additionalProperties": false,
"description": "Attributes for recommendation boosting"
},
"UserToItemsRequest": {
"title": "UserToItemsRequest",
"type": "object",
"properties": {
"engine_id": {
"title": "Engine Id",
"type": "string",
"description": "\nThe engine you want to get results from. When you have more than one engine, you can use this parameter to\nspecify the specific engine you want to get results from. If not specified, the default engine will be used.\n"
},
"user_id": {
"title": "User Id",
"type": "string",
"description": "\nThe user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead.\n"
},
"anonymous_id": {
"title": "Anonymous Id",
"type": "string",
"description": "The anonymous visitor who made the query and for whom Miso will personalize the results. Either\n `user_id` or `anonymous_id` needs to be specified for personalization to work. "
},
"user_hash": {
"title": "User Hash",
"type": "string",
"description": "\nThe hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key).\n`user_hash` is required to prevent unauthorized API access if you are\nmaking API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key).\n\nYou should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your\n[Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server,\nand then let the front-end code send the generated user_hash to Miso APIs to\nverify the identity of the API caller.\n\nAs long as the [Secret API Key](#section/Authentication/Secret%20API%20Key)\n is kept secret, the user_hash prevents a malicious attacker from making unauthorized\nAPI calls or impersonating any of your users.\n\nMiso APIs accept the case-incentive \"hex digest\" of user hash, a sample Python 3 code to generate it on your backend server\nis as follow:\n\n```python\nimport hashlib\nimport hmac\n\nYOUR_MISO_SECRET_API_KEY = \"039c501ac8dfcac91\"\nkey_bytes = YOUR_MISO_SECRET_API_KEY.encode()\nuser_id = \"USER_123\" # or anonymous_id\nuser_id_bytes = user_id.encode()\nuser_hash = hmac.new(\n key_bytes,\n user_id_bytes,\n hashlib.sha256).hexdigest()\n# user_hash is \"7eb04da5e...\"\n```\n\nYou can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e)\n"
},
"user_cohort": {
"title": "User Cohort",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
]
},
"description": "\nThe user cohort you want to cold-start the recommendation with. For example, the following query will make\nrecommendations based on the preferences of the users whose `country=\"United States\"`, and `gender=\"Female\"`\nin the User Profile dataset.\n```\n{\n \"user_cohort\": {\n \"country\": \"United States\",\n \"gender\": \"Female\"\n }\n}\n```\n"
},
"rows": {
"title": "Rows",
"type": "integer",
"description": "Number of product recommendations to return",
"default": 5
},
"type": {
"title": "Type",
"type": "string",
"description": "\nThe type of products to return. Use this parameter to make the API return only\na certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)).\n\nThis is particularly useful for sites that have multiple types of products:\nFor example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can\nthen use type parameter to limit the recommendation or search results to return only one kind of them.\n\nFor instance, the following query will return only *store* products:\n ```\n{\"type\": \"store\"}\n ```\n\nFor another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*,\nthree kinds\nof products. You can use `type` parameter to limit results to one kind of them. For instance, the following\nquery will limit the results to only *hotels* product:\n ```\n{\"type\": \"hotel\"}\n ```\n"
},
"dedupe_product_group_id": {
"title": "Dedupe Product Group Id",
"type": "boolean",
"description": "\nWhether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`,\nMiso will prevent products with the same `product_group_id` from showing multiple\ntimes in the search or recommendation results.\n\n\nThis is particular useful when one product has multiple variants (for example, different\nsizes, colors, or materials), and you only want to show this product only once in the search or recommendation\nresults. Miso will then return the variant that is most likely to be of the user's interest.\n",
"default": true
},
"additional_interactions": {
"title": "Additional Interactions",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ProductDetailPageView"
},
{
"$ref": "#/components/schemas/Search"
},
{
"$ref": "#/components/schemas/AddToCart"
},
{
"$ref": "#/components/schemas/RemoveFromCart"
},
{
"$ref": "#/components/schemas/Checkout"
},
{
"$ref": "#/components/schemas/Refund"
},
{
"$ref": "#/components/schemas/Subscribe"
},
{
"$ref": "#/components/schemas/Unsubscribe"
},
{
"$ref": "#/components/schemas/AddToCollection"
},
{
"$ref": "#/components/schemas/RemoveFromCollection"
},
{
"$ref": "#/components/schemas/Read"
},
{
"$ref": "#/components/schemas/Watch"
},
{
"$ref": "#/components/schemas/Listen"
},
{
"$ref": "#/components/schemas/Like"
},
{
"$ref": "#/components/schemas/Dislike"
},
{
"$ref": "#/components/schemas/Share"
},
{
"$ref": "#/components/schemas/Rate"
},
{
"$ref": "#/components/schemas/Bookmark"
},
{
"$ref": "#/components/schemas/Complete"
},
{
"$ref": "#/components/schemas/Feedback"
},
{
"$ref": "#/components/schemas/Impression"
},
{
"$ref": "#/components/schemas/ViewableImpression"
},
{
"$ref": "#/components/schemas/Click"
},
{
"$ref": "#/components/schemas/Submit"
},
{
"$ref": "#/components/schemas/HomePageView"
},
{
"$ref": "#/components/schemas/CategoryPageView"
},
{
"$ref": "#/components/schemas/PromoPageView"
},
{
"$ref": "#/components/schemas/ProductImageView"
},
{
"$ref": "#/components/schemas/Custom"
}
]
},
"description": "\nA list of additional interaction records. You can use this fields to simulate user interactions without\nactually writing them to the interaction dataset.\n",
"default": []
},
"fl": {
"title": "Fl",
"type": "array",
"items": {
"type": "string"
},
"description": "\nList of fields to retrieve. For example, the following request retrieves only the `title` field of each product along\nwith the `product_id`, which is always returned.\n\n```\n{\"fl\": [\"title\"]}\n```\n\nYou can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title`\nand any custom attributes under the `attributes` dictionary.\n\n```\n{\"fl\": [\"title\", \"attributes.*\"]}\n```\n\nThe following retrieves all the available fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default).\n```\n{\"fl\": []}\n```\n",
"default": []
},
"exclude": {
"title": "Exclude",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of `product_ids` of products you want to *exclude* from search results."
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nIn certain cases, Miso will take these variables into account when generating results.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "\nWhen `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s),\nthose boost rules will be matched, regardless if the criteria is met or not.\n\nUseful when want to force trigger specific boost campaign.\n",
"default": [],
"example": [
"tag-1",
"quetag-2"
]
},
"fq": {
"title": "Fq",
"type": "string",
"description": "\n\nDefines a query in Solr syntax that can be used to restrict the superset of\nproducts to return, without influencing the overall ranking. `fq` can enable users to drill down to products\nwith specific features based on different product attributes\n\nFor example, the query below limits the search results to only show products whose size is either `M` or `S` and\nbrand is `Nike`:\n\n```\n{\"fq\": \"size:(\\\"M\\\" OR \\\"S\\\") AND brand:\\\"Nike\\\"\"}\n```\n\nYou can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the\nsearch results to only products whose `designer` attribute is `Calvin Klein`\n\n```\n{\"fq\": \"attributes.designer:\\\"Calvin Klein\\\"\"}\n```\n\n`fq` can also limit search results by numerical range. For example, the following query limits the results to\nproducts that have `rating >= 4`.\n\n```\n{\"fq\": \"rating:[4 TO *]\"}\n```\n"
},
"boost_fq": {
"title": "Boost Fq",
"type": "string",
"description": "\nDefines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to\nspecific *boost positions* (See `boost_positions` parameter below.)\nFor example, the query below will promote all the relevant products whose brand is `Nike` to the top of\nrecommendation list:\n\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\"\n}\n```\n\nFor a slightly more complex example, the query below will promote the Nike products which have also been tagged\nas `ON SALE` to the top of the ranking:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\"\n}\n```\nIt is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert,\nand will not boost a low performance product only because it matches the boosting query.\n\nDepending on your boosting rules, in certain cases, you would like to prevent recommendation results from being\ntoo monotone due to boosting. With Miso, you have two tools to do so.\n\nFirst, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For\nexample, the query below will place boosted products only at the first and fourth places in the ranking\n(positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"boost_positions\": [0, 3]\n}\n```\n\nThe second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to\nmaintain a minimum distance between products that have the same attributes. For example, the following query\nwill place products made by the same brand apart from each other.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"diversification\": {\n \"brand\": {\"minimum_distance\": 1}\n }\n}\n```\n"
},
"boost_positions": {
"title": "Boost Positions",
"type": "array",
"items": {
"type": "integer"
},
"description": "\nDefines a list of 0-based positions you want to place the boosted products at.\n\nFor example, the query below will promote products whose brand is `Nike` as the top and second recommendations:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n}\n```\nIf `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked\nhigher than the rest of the products.\n"
},
"boost_rule_name": {
"title": "Boost Rule Name",
"type": "string",
"description": "Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response"
},
"boost_rules": {
"title": "Boost Rules",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostingFilterBase"
},
"description": "\nDefine a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules`\nparameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different\npositions. For example, the query below will promote products whose brand is `Nike` to the top\nand second results, and products whose brand is `Adidas` to the third and fourth results:\n```\n{\n \"boost_rules\": [\n {\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n },\n {\n \"boost_fq\": \"brand:\\\"Adidas\\\"\",\n \"boost_positions\": [2, 3]\n }\n ]\n}\n```\n",
"default": []
},
"geo": {
"title": "Geo",
"allOf": [
{
"$ref": "#/components/schemas/GeoQuery"
}
],
"description": "\nWhen set, filter result to include only products within certain geographic range from given point will be returned,\nor to boost product within the same range.\n\nProduct should have a field that holds the location of the product, `location` is used by default,\nbut other field can also be used.\n\nDistance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used.\n\nFor example, to limit results to products within 100 miles of New York city:\n```\n{\n \"geo\": {\n \"filter\": [{\n \"lat\": 40.73061,\n \"lon\": -73.93524,\n \"distance\": 100\n }]\n }\n}\n```\n\nTo boost products within 2 kilometers around Alcatraz Island according to `loc` field:\n```\n{\n \"geo\": {\n \"boost\": [{\n \"field\": \"loc\",\n \"lat\": 37.82667,\n \"lon\": -122.42278,\n \"distance\": 2,\n \"distance_unit\": \"km\"\n }]\n }\n}\n```\n"
},
"diversification": {
"title": "Diversification",
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/DiversifyField"
},
"description": "\n\nDefines diversification rules to prevent products with the same attributes (e.g. sneakers made by the same brand\nor books from the same authors) from showing up too close to each other in the results.\n\nFor instance, customers who have purchased many of sneakers from Nike may happen to have recommendations or\nsearch results where all top-5 entries are sneakers made by Nike. Purely considering accuracy, these\nrecommendations appear excellent since the user clearly appreciates Nike sneakers. However,\nsuch results might be considered too \"plain\" by the user, owing to its lack of diversity.\n\n`diversification` parameter allows you to avoid this problem by enforcing a desired *minimum distance* between\nproducts. For example, consider a list of four products whose `brand` are *Nike, Nike, Adidas,* and *PUMA*\nrespectively. The query below will make sure there are at least one different product between two Nike\nproducts, e.g. the diversified ranking may become *Nike, Adidas, Nike,* and *PUMA* :\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 1}}\n}\n```\n\nYou can also increase the minimum_distance to place products further apart. For example, the following query will\nmake sure, for the two Nike products, there are at least *two* other products between them.\nAs a result, the diversified ranking may become *Nike, Adidas, PUMA*, and *Nike*.:\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 2}}\n}\n```\n\nThe diversification algorithm reranks the products on a best-effort basis. For example, for the product list\ndescribed earlier, it is not possible to place two Nike product three places apart from each other. Therefore,\nthe diversified ranking will still remain *Nike, Adidas, PUMA,* and Nike* even if we set `minimum_distance=3`.\n"
},
"dithering": {
"title": "Dithering",
"minimum": 1.0,
"type": "number",
"description": "\nDithering is an optional parameter (>= 1.0, and typically <= 5.0) in the recommendation APIs that introduces randomness to the order of\nrecommended items. By adding noise to the original ranking, it shuffles the list, surfacing lower-ranked\nitems to enhance list freshness and potentially boost user engagement. However, excessive dithering may reduce the accuracy\nof item ordering. See [this blog post](https://buildingrecommenders.wordpress.com/2015/11/11/dithering/) for more information.\n",
"default": 1.0
},
"pagination_id": {
"title": "Pagination Id",
"maxLength": 512,
"type": "string",
"description": "\nA unique identifier to enable pagination in Recommendation APIs. By default, Recommendation APIs do not support\npagination because the results from Miso, by its natural, will change in real-time with new user interactions.\n`pagination_id` allows you to implement pagination more easily by memorize what products we have\nreturned to the current user with the same `pagination_id`.\n\nTo enable pagination, you generate a `pagination_id` and set it in the first and subsequent requests in the same browsing session\nwhere you want to enable pagination. With `pagination_id` set, you can access recommendations\nin different pages using the combination of `start` and `rows` parameters, and Miso will ensure that no duplicated\nrecommendation will be returned in different pages.\n\nFor example, assuming you are implementing an infinite scroll with Miso Recommendation APIs. Before you make the first request,\nyou generate a `pagination_id` using the `current datetime` or `uuid` like the following:\n```javascript\n// current datetime\nvar my_pagination_id = Date.now().toString()\n// OR uuid\nconst uuidv4 = require(\"uuid/v4\")\nvar my_pagination_id = uuidv4()\n```\nYou can then request the first page of results with `my_pagination_id` like the following:\n```javascript\n{\n \"pagination_id\": my_pagination_id,\n \"start\": 0,\n \"rows\": 10\n}\n```\nThen, you can request the next page of results with the same `my_pagination_id`, and Miso will ensure\nthat no duplicated result is returned:\n```javascript\n{\n \"pagination_id\": my_pagination_id,\n \"start\": 10,\n \"rows\": 10\n}\n```\n\nNote that, a `pagination_id` will timeout if there is no further request associated with it for 30 minutes.\nAlso, `pagination_id` is scoped by individual users: i.e. different users' results will not be affected\neven if they use the same `pagination_id`.\n"
},
"start": {
"title": "Start",
"type": "integer",
"description": "\nThe start of the page you want to access. Combine this with `rows` to implement pagination. You can only set it when `pagination_id` is given.\n",
"default": 0
}
},
"additionalProperties": false,
"description": "Attributes for recommendation boosting"
},
"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"
}
}
},
"VariantObject": {
"title": "VariantObject",
"required": [
"id",
"name",
"slug",
"status"
],
"type": "object",
"properties": {
"id": {
"title": "Id",
"type": "string",
"description": "The UUID of this variant.",
"example": "59769b89-5f1f-46d5-a4fa-a583ebd2f7fd"
},
"name": {
"title": "Name",
"type": "string",
"description": "The name of this variant.",
"example": "Treatment_Group"
},
"slug": {
"title": "Slug",
"type": "string",
"description": "The slug name of this variant.",
"example": "Treatment_Group"
},
"configuration": {
"title": "Configuration",
"anyOf": [
{
"type": "object"
},
{
"type": "array",
"items": {}
},
{
"type": "string"
}
],
"description": "The configuration of this variant.",
"example": {
"model": "A"
}
},
"status": {
"title": "Status",
"enum": [
"Draft",
"Scheduled",
"Active",
"Completed",
"Archived"
],
"type": "string",
"description": "The current status for this variant.",
"example": "Active"
}
}
},
"ViewableImpression": {
"title": "viewable_impression",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"viewable_impression"
],
"type": "string",
"description": "\nWhen a product or content asset is presented to the user, it is not guarantee that the user will see it.\n\nAn viewable impression is an impression that is \"viewable\" by the user.\nUsually, content asset is considered viewable if more than 50% of its area is visible on screen.\n\nYou can also use different definition for what is considered viewable.\nMiso will automatically find the best recommendation as long as the difference between\nviewable and non-viewable impression is consistant.\n"
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"Watch": {
"title": "watch",
"required": [
"type"
],
"type": "object",
"properties": {
"type": {
"title": "Type",
"enum": [
"watch"
],
"type": "string",
"description": "\nUsed to record when and for how long a user watches content that is of a video format.\n"
},
"duration": {
"title": "Duration",
"type": "number",
"description": "\nHow long (in seconds) the user stayed on this page, or consumed (listened, read, or watched) a product. This field is\noptional, but it's very important in scenarios where consumption duration matters, including\n`product_detail_page_view`, `category_page_view`, `watch`, `listen`, and `read`. For example, if a user only\nviews or consumes a product for less than 5 seconds, that user is probably not interested in the product. On\nthe other hand, if a user stays on a page for a while, it usually means they are seriously engaging with or\nconsidering the product. When `duration` is absent, we will use the timestamp of the next interaction to\ninfer a rough duration value.\n\nExample:\n```\n{\"duration\": 61.5}\n```\n",
"example": 61.5
},
"product_ids": {
"title": "Product Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nProducts or content the user is interacting with. This field is required by\nalmost all the interaction types. We use `product_ids` to refer to the product / content records that you upload to Miso.\nTherefore, it is important to keep this consistent between the two datasets.\n\nExample:\n```\n{\"product_ids\": [\"123ABC-BLACK\", \"123EFG-YELLOW\"]}\n```\n",
"default": [],
"example": [
"123ABC-BLACK"
]
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string",
"maxLength": 512
},
"description": "\nThe product groups the user is interacting with. You only need this field if you model product\nvariants using `product_id` and `product_group_id` (see Product API). If so, you should use this field, when a\nuser is interacting with a *product group* rather than a specific product variant, for example, when the user\nis viewing the master page of a T-shirt (i.e. a product group), but has not selected the specific size or\ncolor (i.e. a product variant) yet.\n\nIn such situations, the `product_id` is not applicable because we only know the user is interested in\nthis T-shirt (a product group), but don't know which particular product variant the user is interested in.\nTherefore, we use `product_group_ids` to capture such interactions in place of `product_ids`.\n\nIn the situations where specific `product_ids` are available, for example, when user selected a particular size\nof the T-Shirt, use `product_ids` instead.\n\n\nExample:\n```\n{\"product_group_ids\": [\"123ABC\"]}\n```\n",
"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(:::)`. 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": "\nThe ISO-8601 timestamp specifying when the interaction occurred. If the interaction just happened, leave it out and we\nwill default to the server's time. If you're importing data from the past, make sure you provide a\ntimestamp. It is recommended to include milliseconds in the timestamp to provide a higher time resolution.\n\nExample:\n```\n{\"timestamp\": \"2018-11-07T00:25:00.073876Z\"}\n```\n",
"format": "date-time"
},
"miso_id": {
"title": "Miso Id",
"type": "string",
"description": "\nMiso-generated unique Id for each recommendation or search result. Maintaining this Id for\nsubsequent page views is important to Miso's performance, as we use `miso_id` to track and fine-tune the\nperformance of personalization and search results. When a user clicks on a recommendation or search result,\nyou should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the\ninteractions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`,\n`add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't.\n\nExample:\n```\n{\"misoId\": \"123e4567-e89b-12d3-a456-426614174000\"}\n```\n",
"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
},
"WebBasedContext": {
"title": "WebBasedContext",
"type": "object",
"properties": {
"campaign": {
"title": "Campaign",
"allOf": [
{
"$ref": "#/components/schemas/Campaign"
}
],
"description": "\nThe campaign that resulted in the interaction. Campaign dictionary contains standard UTM parameters: `name`,\n`source`, `medium`, `term`, `content`. We use campaign information to infer users' interests and fine-tune the\npersonalization and search results based on the current user's campaign information.\n"
},
"truncated_ip": {
"title": "Truncated Ip",
"type": "string",
"description": "\nUser's truncated IP address. We use IP address to determine the country of the users.\n",
"format": "ipv4",
"example": "1.1.1.0"
},
"locale": {
"title": "Locale",
"type": "string",
"description": "Locale string of the current session, for example en-US.",
"example": "en-US"
},
"region": {
"title": "Region",
"type": "string",
"description": "\nThe region/location of the site the user is visiting. This is for sites that serve different regions or\nmarkets. You can define your own region keywords, for example, `US East`, `Europe`, `LATM`, etc.\n",
"example": "US East"
},
"page": {
"title": "Page",
"allOf": [
{
"$ref": "#/components/schemas/Page"
}
],
"description": "The current page in the browser. Page dictionary containing referrer, title and url. we will use page view\n as a pseudo interaction to infer users' interest. "
},
"user_agent": {
"title": "User Agent",
"type": "string",
"description": "\nUser agent of the device making the request. We use this to determine if a user is browsing the site on\nmobile or desktop, and tailor the recommendations and search results accordingly.\n\nExample:\n```\n{\"user_agent\":\n \"Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0\"}\n```\n",
"example": "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko/20100101 Firefox/47.0"
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "number"
}
},
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "array",
"items": {
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "integer"
},
{
"type": "boolean"
}
]
}
}
}
]
},
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nMiso will take these variables into account when generating recommendations.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
}
}
},
"YMALRequest": {
"title": "YMALRequest",
"type": "object",
"properties": {
"product_id": {
"title": "Product Id",
"minLength": 1,
"type": "string",
"description": "\nThe `product_id` of the *anchor* product. The returned recommendations will be\nthe products that are similar or are liked by the same users who also like the anchor product.\n"
},
"product_ids": {
"title": "Product Ids",
"minLength": 1,
"type": "array",
"items": {
"type": "string",
"minLength": 1
},
"description": "\nThe `product_ids` of a **list** of *anchor* products. The returned recommendations will be\nthe products that are similar or are liked by the same users who also like these anchor products. For example,\nyou can use the products in a user's shopping cart as the anchor products to make purchase recommendations\nfor this user.\n"
},
"product_group_id": {
"title": "Product Group Id",
"minLength": 1,
"type": "string",
"description": "\nThe `product_group_id` of the *anchor* product group. The returned recommendations will be\nthe products that are similar or are liked by the same users who also like the anchor *product group*.\n\nYou should use `product_group_id` on a *product\ngroup* page, before users select a specific product variant. For example, you should use `product_group_id`\non the product group page of a T-shirt, and use `product_id`, once user choose any specific size or color\nvariants of the T-shirt.\n"
},
"product_group_ids": {
"title": "Product Group Ids",
"type": "array",
"items": {
"type": "string"
},
"description": "\nThe `product_group_ids` of the *anchor* product groups. The returned recommendations will be\nthe products that are similar or are liked by the same users who also like the anchor *product groups*.\n\nYou should use `product_group_ids` in pages you want to recommend products related to multiple product groups.\n"
},
"buy_together": {
"title": "Buy Together",
"type": "boolean",
"description": "\nWhether to focus on the Products that are frequently *bought together*. `buy_together` parameter is by default `false`,\nwhich make the *Product To Products API* focus on Products that are related to the anchor products, e.g. the products\nwith similar contents or frequently attract the interests of the same group of users.\n\nWhen `buy_together=true`, the ProductToProducts API will focus on the type of Products that are more frequently bought\ntogether along with the anchor product(s) in the same transactions or session.\n\n",
"default": false
},
"engine_id": {
"title": "Engine Id",
"type": "string",
"description": "\nThe engine you want to get results from. When you have more than one engine, you can use this parameter to\nspecify the specific engine you want to get results from. If not specified, the default engine will be used.\n"
},
"user_id": {
"title": "User Id",
"type": "string",
"description": "\nThe user who made the query and for whom Miso will personalize the results. For an anonymous visitor, use `anonymous_id` instead.\n"
},
"anonymous_id": {
"title": "Anonymous Id",
"type": "string",
"description": "The anonymous visitor who made the query and for whom Miso will personalize the results. Either\n `user_id` or `anonymous_id` needs to be specified for personalization to work. "
},
"user_hash": {
"title": "User Hash",
"type": "string",
"description": "\nThe hash of `user_id` (or `anonymous_id`) encrypted by your [Secret API Key](#section/Authentication/Secret%20API%20Key).\n`user_hash` is required to prevent unauthorized API access if you are\nmaking API calls with a [Publishable API Key](#section/Authentication/Publishable%20API%20Key).\n\nYou should generate the user_hash via HMAC scheme: you encrypt the desired user_id (or anonymous_id) with your\n[Secret API Key](#section/Authentication/Secret%20API%20Key) on your backend server,\nand then let the front-end code send the generated user_hash to Miso APIs to\nverify the identity of the API caller.\n\nAs long as the [Secret API Key](#section/Authentication/Secret%20API%20Key)\n is kept secret, the user_hash prevents a malicious attacker from making unauthorized\nAPI calls or impersonating any of your users.\n\nMiso APIs accept the case-incentive \"hex digest\" of user hash, a sample Python 3 code to generate it on your backend server\nis as follow:\n\n```python\nimport hashlib\nimport hmac\n\nYOUR_MISO_SECRET_API_KEY = \"039c501ac8dfcac91\"\nkey_bytes = YOUR_MISO_SECRET_API_KEY.encode()\nuser_id = \"USER_123\" # or anonymous_id\nuser_id_bytes = user_id.encode()\nuser_hash = hmac.new(\n key_bytes,\n user_id_bytes,\n hashlib.sha256).hexdigest()\n# user_hash is \"7eb04da5e...\"\n```\n\nYou can find more examples for other languages in this [Github Gist](https://gist.github.com/thewheat/7342c76ade46e7322c3e)\n"
},
"user_cohort": {
"title": "User Cohort",
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "string"
}
]
},
"description": "\nThe user cohort you want to cold-start the recommendation with. For example, the following query will make\nrecommendations based on the preferences of the users whose `country=\"United States\"`, and `gender=\"Female\"`\nin the User Profile dataset.\n```\n{\n \"user_cohort\": {\n \"country\": \"United States\",\n \"gender\": \"Female\"\n }\n}\n```\n"
},
"rows": {
"title": "Rows",
"type": "integer",
"description": "Number of product recommendations to return",
"default": 5
},
"type": {
"title": "Type",
"type": "string",
"description": "\nThe type of products to return. Use this parameter to make the API return only\na certain type of products (see [Product APIs](#operation/content_write_api_v1_products_post)).\n\nThis is particularly useful for sites that have multiple types of products:\nFor example, on a marketplace site, YOu may model *merchandise* and *store* as two types of *products*. You can\nthen use type parameter to limit the recommendation or search results to return only one kind of them.\n\nFor instance, the following query will return only *store* products:\n ```\n{\"type\": \"store\"}\n ```\n\nFor another example, on a travel website, you might have: *hotel*, *thing to do*, and *restaurant*,\nthree kinds\nof products. You can use `type` parameter to limit results to one kind of them. For instance, the following\nquery will limit the results to only *hotels* product:\n ```\n{\"type\": \"hotel\"}\n ```\n"
},
"dedupe_product_group_id": {
"title": "Dedupe Product Group Id",
"type": "boolean",
"description": "\nWhether to dedupe product based on `product_group_id`. If `dedupe_product_group_id=true`,\nMiso will prevent products with the same `product_group_id` from showing multiple\ntimes in the search or recommendation results.\n\n\nThis is particular useful when one product has multiple variants (for example, different\nsizes, colors, or materials), and you only want to show this product only once in the search or recommendation\nresults. Miso will then return the variant that is most likely to be of the user's interest.\n",
"default": true
},
"additional_interactions": {
"title": "Additional Interactions",
"type": "array",
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/ProductDetailPageView"
},
{
"$ref": "#/components/schemas/Search"
},
{
"$ref": "#/components/schemas/AddToCart"
},
{
"$ref": "#/components/schemas/RemoveFromCart"
},
{
"$ref": "#/components/schemas/Checkout"
},
{
"$ref": "#/components/schemas/Refund"
},
{
"$ref": "#/components/schemas/Subscribe"
},
{
"$ref": "#/components/schemas/Unsubscribe"
},
{
"$ref": "#/components/schemas/AddToCollection"
},
{
"$ref": "#/components/schemas/RemoveFromCollection"
},
{
"$ref": "#/components/schemas/Read"
},
{
"$ref": "#/components/schemas/Watch"
},
{
"$ref": "#/components/schemas/Listen"
},
{
"$ref": "#/components/schemas/Like"
},
{
"$ref": "#/components/schemas/Dislike"
},
{
"$ref": "#/components/schemas/Share"
},
{
"$ref": "#/components/schemas/Rate"
},
{
"$ref": "#/components/schemas/Bookmark"
},
{
"$ref": "#/components/schemas/Complete"
},
{
"$ref": "#/components/schemas/Feedback"
},
{
"$ref": "#/components/schemas/Impression"
},
{
"$ref": "#/components/schemas/ViewableImpression"
},
{
"$ref": "#/components/schemas/Click"
},
{
"$ref": "#/components/schemas/Submit"
},
{
"$ref": "#/components/schemas/HomePageView"
},
{
"$ref": "#/components/schemas/CategoryPageView"
},
{
"$ref": "#/components/schemas/PromoPageView"
},
{
"$ref": "#/components/schemas/ProductImageView"
},
{
"$ref": "#/components/schemas/Custom"
}
]
},
"description": "\nA list of additional interaction records. You can use this fields to simulate user interactions without\nactually writing them to the interaction dataset.\n",
"default": []
},
"fl": {
"title": "Fl",
"type": "array",
"items": {
"type": "string"
},
"description": "\nList of fields to retrieve. For example, the following request retrieves only the `title` field of each product along\nwith the `product_id`, which is always returned.\n\n```\n{\"fl\": [\"title\"]}\n```\n\nYou can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title`\nand any custom attributes under the `attributes` dictionary.\n\n```\n{\"fl\": [\"title\", \"attributes.*\"]}\n```\n\nThe following retrieves all the available fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array to retrieve just the `product_id` field (which is the default).\n```\n{\"fl\": []}\n```\n",
"default": []
},
"exclude": {
"title": "Exclude",
"type": "array",
"items": {
"type": "string"
},
"description": "An array of `product_ids` of products you want to *exclude* from search results."
},
"custom_context": {
"title": "Custom Context",
"type": "object",
"description": "\nDictionary of custom context variables for the current browsing session. You can specify context variables\nspecific to your websites or apps in a `{\"KEY\":VALUE}` format, where `KEY` must be a string, and `VALUE` can be:\n* a `bool`\n* a `string` or an `array of string`\n* a `number` or an `array of numbers`\n* an `array of objects`\n* `null`\n\nIn certain cases, Miso will take these variables into account when generating results.\n",
"example": {
"session_variable_1": [
"value_1",
"value_2"
]
}
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "\nWhen `boosting_tags` is given, and there are pre-defined boost rules have the same tag(s),\nthose boost rules will be matched, regardless if the criteria is met or not.\n\nUseful when want to force trigger specific boost campaign.\n",
"default": [],
"example": [
"tag-1",
"quetag-2"
]
},
"fq": {
"title": "Fq",
"type": "string",
"description": "\n\nDefines a query in Solr syntax that can be used to restrict the superset of\nproducts to return, without influencing the overall ranking. `fq` can enable users to drill down to products\nwith specific features based on different product attributes\n\nFor example, the query below limits the search results to only show products whose size is either `M` or `S` and\nbrand is `Nike`:\n\n```\n{\"fq\": \"size:(\\\"M\\\" OR \\\"S\\\") AND brand:\\\"Nike\\\"\"}\n```\n\nYou can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the\nsearch results to only products whose `designer` attribute is `Calvin Klein`\n\n```\n{\"fq\": \"attributes.designer:\\\"Calvin Klein\\\"\"}\n```\n\n`fq` can also limit search results by numerical range. For example, the following query limits the results to\nproducts that have `rating >= 4`.\n\n```\n{\"fq\": \"rating:[4 TO *]\"}\n```\n"
},
"boost_fq": {
"title": "Boost Fq",
"type": "string",
"description": "\nDefines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to\nspecific *boost positions* (See `boost_positions` parameter below.)\nFor example, the query below will promote all the relevant products whose brand is `Nike` to the top of\nrecommendation list:\n\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\"\n}\n```\n\nFor a slightly more complex example, the query below will promote the Nike products which have also been tagged\nas `ON SALE` to the top of the ranking:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\"\n}\n```\nIt is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert,\nand will not boost a low performance product only because it matches the boosting query.\n\nDepending on your boosting rules, in certain cases, you would like to prevent recommendation results from being\ntoo monotone due to boosting. With Miso, you have two tools to do so.\n\nFirst, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For\nexample, the query below will place boosted products only at the first and fourth places in the ranking\n(positions are 0-based), and place the remaining products in their original ranking, skipping these two positions.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"boost_positions\": [0, 3]\n}\n```\n\nThe second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to\nmaintain a minimum distance between products that have the same attributes. For example, the following query\nwill place products made by the same brand apart from each other.\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\" AND tags:\\\"ON SALE\\\"\",\n \"diversification\": {\n \"brand\": {\"minimum_distance\": 1}\n }\n}\n```\n"
},
"boost_positions": {
"title": "Boost Positions",
"type": "array",
"items": {
"type": "integer"
},
"description": "\nDefines a list of 0-based positions you want to place the boosted products at.\n\nFor example, the query below will promote products whose brand is `Nike` as the top and second recommendations:\n```\n{\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n}\n```\nIf `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked\nhigher than the rest of the products.\n"
},
"boost_rule_name": {
"title": "Boost Rule Name",
"type": "string",
"description": "Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response"
},
"boost_rules": {
"title": "Boost Rules",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostingFilterBase"
},
"description": "\nDefine a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules`\nparameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different\npositions. For example, the query below will promote products whose brand is `Nike` to the top\nand second results, and products whose brand is `Adidas` to the third and fourth results:\n```\n{\n \"boost_rules\": [\n {\n \"boost_fq\": \"brand:\\\"Nike\\\"\",\n \"boost_positions\": [0, 1]\n },\n {\n \"boost_fq\": \"brand:\\\"Adidas\\\"\",\n \"boost_positions\": [2, 3]\n }\n ]\n}\n```\n",
"default": []
},
"geo": {
"title": "Geo",
"allOf": [
{
"$ref": "#/components/schemas/GeoQuery"
}
],
"description": "\nWhen set, filter result to include only products within certain geographic range from given point will be returned,\nor to boost product within the same range.\n\nProduct should have a field that holds the location of the product, `location` is used by default,\nbut other field can also be used.\n\nDistance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used.\n\nFor example, to limit results to products within 100 miles of New York city:\n```\n{\n \"geo\": {\n \"filter\": [{\n \"lat\": 40.73061,\n \"lon\": -73.93524,\n \"distance\": 100\n }]\n }\n}\n```\n\nTo boost products within 2 kilometers around Alcatraz Island according to `loc` field:\n```\n{\n \"geo\": {\n \"boost\": [{\n \"field\": \"loc\",\n \"lat\": 37.82667,\n \"lon\": -122.42278,\n \"distance\": 2,\n \"distance_unit\": \"km\"\n }]\n }\n}\n```\n"
},
"diversification": {
"title": "Diversification",
"type": "object",
"additionalProperties": {
"$ref": "#/components/schemas/DiversifyField"
},
"description": "\n\nDefines diversification rules to prevent products with the same attributes (e.g. sneakers made by the same brand\nor books from the same authors) from showing up too close to each other in the results.\n\nFor instance, customers who have purchased many of sneakers from Nike may happen to have recommendations or\nsearch results where all top-5 entries are sneakers made by Nike. Purely considering accuracy, these\nrecommendations appear excellent since the user clearly appreciates Nike sneakers. However,\nsuch results might be considered too \"plain\" by the user, owing to its lack of diversity.\n\n`diversification` parameter allows you to avoid this problem by enforcing a desired *minimum distance* between\nproducts. For example, consider a list of four products whose `brand` are *Nike, Nike, Adidas,* and *PUMA*\nrespectively. The query below will make sure there are at least one different product between two Nike\nproducts, e.g. the diversified ranking may become *Nike, Adidas, Nike,* and *PUMA* :\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 1}}\n}\n```\n\nYou can also increase the minimum_distance to place products further apart. For example, the following query will\nmake sure, for the two Nike products, there are at least *two* other products between them.\nAs a result, the diversified ranking may become *Nike, Adidas, PUMA*, and *Nike*.:\n```\n{\n \"diversification\": {\"brand\": {\"minimum_distance\": 2}}\n}\n```\n\nThe diversification algorithm reranks the products on a best-effort basis. For example, for the product list\ndescribed earlier, it is not possible to place two Nike product three places apart from each other. Therefore,\nthe diversified ranking will still remain *Nike, Adidas, PUMA,* and Nike* even if we set `minimum_distance=3`.\n"
},
"dithering": {
"title": "Dithering",
"minimum": 1.0,
"type": "number",
"description": "\nDithering is an optional parameter (>= 1.0, and typically <= 5.0) in the recommendation APIs that introduces randomness to the order of\nrecommended items. By adding noise to the original ranking, it shuffles the list, surfacing lower-ranked\nitems to enhance list freshness and potentially boost user engagement. However, excessive dithering may reduce the accuracy\nof item ordering. See [this blog post](https://buildingrecommenders.wordpress.com/2015/11/11/dithering/) for more information.\n",
"default": 1.0
},
"pagination_id": {
"title": "Pagination Id",
"maxLength": 512,
"type": "string",
"description": "\nA unique identifier to enable pagination in Recommendation APIs. By default, Recommendation APIs do not support\npagination because the results from Miso, by its natural, will change in real-time with new user interactions.\n`pagination_id` allows you to implement pagination more easily by memorize what products we have\nreturned to the current user with the same `pagination_id`.\n\nTo enable pagination, you generate a `pagination_id` and set it in the first and subsequent requests in the same browsing session\nwhere you want to enable pagination. With `pagination_id` set, you can access recommendations\nin different pages using the combination of `start` and `rows` parameters, and Miso will ensure that no duplicated\nrecommendation will be returned in different pages.\n\nFor example, assuming you are implementing an infinite scroll with Miso Recommendation APIs. Before you make the first request,\nyou generate a `pagination_id` using the `current datetime` or `uuid` like the following:\n```javascript\n// current datetime\nvar my_pagination_id = Date.now().toString()\n// OR uuid\nconst uuidv4 = require(\"uuid/v4\")\nvar my_pagination_id = uuidv4()\n```\nYou can then request the first page of results with `my_pagination_id` like the following:\n```javascript\n{\n \"pagination_id\": my_pagination_id,\n \"start\": 0,\n \"rows\": 10\n}\n```\nThen, you can request the next page of results with the same `my_pagination_id`, and Miso will ensure\nthat no duplicated result is returned:\n```javascript\n{\n \"pagination_id\": my_pagination_id,\n \"start\": 10,\n \"rows\": 10\n}\n```\n\nNote that, a `pagination_id` will timeout if there is no further request associated with it for 30 minutes.\nAlso, `pagination_id` is scoped by individual users: i.e. different users' results will not be affected\neven if they use the same `pagination_id`.\n"
},
"start": {
"title": "Start",
"type": "integer",
"description": "\nThe start of the page you want to access. Combine this with `rows` to implement pagination. You can only set it when `pagination_id` is given.\n",
"default": 0
}
},
"additionalProperties": false,
"description": "Attributes for recommendation boosting"
},
"app__schemas__engine_api__request__PreviewBoosting": {
"title": "PreviewBoosting",
"required": [
"query_option",
"boost_match_type",
"boost",
"position"
],
"type": "object",
"properties": {
"query": {
"title": "Query",
"type": "string",
"description": "The boosting rule query."
},
"queries": {
"title": "Queries",
"type": "array",
"items": {
"type": "string"
},
"description": "Multiple query of the boosting rule."
},
"query_option": {
"title": "Query Option",
"enum": [
"contains",
"not_contain",
"is",
"is_not",
"regex",
"ends_with",
"starts_with"
],
"type": "string",
"description": "The options of the query. Please fill this field with contains, not_contain, is, and is_not value."
},
"filter_query": {
"title": "Filter Query",
"type": "array",
"items": {
"$ref": "#/components/schemas/FilterQueryItem"
},
"description": "The filter queries of the boosting rule."
},
"boost_match_type": {
"title": "Boost Match Type",
"enum": [
"any",
"all"
],
"type": "string",
"description": "Type of the query. Please fill this field with any or all."
},
"boost": {
"title": "Boost",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostItem"
},
"description": "The items of the boosting rule."
},
"position": {
"title": "Position",
"type": "array",
"items": {
"type": "integer"
},
"description": "The position of the boosting rule should occur."
},
"json_asset": {
"title": "Json Asset",
"type": "string",
"description": "The boosting json asset.",
"example": {
"CO": [
{
"product-name": "name",
"product-image-url": "url"
}
]
}
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "The comma-separated boosting tags.",
"example": [
"tag-1",
"tag-2"
]
}
},
"description": "Properties to receive on Boosting creation"
},
"app__schemas__engine_api__request__Question": {
"title": "Question",
"required": [
"question"
],
"type": "object",
"properties": {
"question": {
"title": "Question",
"minLength": 1,
"type": "string",
"description": "The text of question."
},
"weight": {
"title": "Weight",
"type": "number",
"description": "The weight of question.",
"default": 1.0
}
},
"description": "Question object"
},
"app__schemas__engine_api__response__Question": {
"title": "Question",
"required": [
"question"
],
"type": "object",
"properties": {
"question": {
"title": "Question",
"minLength": 1,
"type": "string"
},
"weight": {
"title": "Weight",
"type": "number",
"default": 1.0
}
},
"description": "Question object"
},
"app__schemas__rec_boosting__PreviewBoosting": {
"title": "PreviewBoosting",
"required": [
"api_names",
"boost_match_type",
"boost",
"position"
],
"type": "object",
"properties": {
"api_names": {
"title": "Api Names",
"type": "array",
"items": {
"type": "string"
},
"description": "The api_names values"
},
"anchor_products": {
"title": "Anchor Products",
"type": "array",
"items": {
"type": "string"
},
"description": "The anchor products ids",
"default": []
},
"module_names": {
"title": "Module Names",
"type": "array",
"items": {
"type": "string"
},
"description": "The module name"
},
"boost_match_type": {
"title": "Boost Match Type",
"enum": [
"any",
"all"
],
"type": "string",
"description": "Type of the query. Please fill this field with any or all."
},
"boost": {
"title": "Boost",
"type": "array",
"items": {
"$ref": "#/components/schemas/BoostItem"
},
"description": "The items of the boosting rule."
},
"position": {
"title": "Position",
"type": "array",
"items": {
"type": "integer"
},
"description": "1-based index of the position of the boosting rule should occur.",
"example": [
1,
2
]
},
"boosting_tags": {
"title": "Boosting Tags",
"type": "array",
"items": {
"type": "string"
},
"description": "The comma-separated boosting tags.",
"example": [
"tag-1",
"tag-2"
]
}
},
"description": "Attributes of boosting"
}
},
"securitySchemes": {
"Secret API Key": {
"type": "apiKey",
"description": "\nYour secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend \nserver. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it \nin [Dojo](https://dojo.askmiso.com/docs/api-browser) and get a new one.\n\nSpecify your secret key in the `api_key` query parameter. For example:\n```\nPOST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17\n```\n\n",
"in": "query",
"name": "api_key"
},
"Publishable API Key": {
"type": "apiKey",
"description": "\nYour publishable API key is used to call Miso's APIs from your front-end code. It can be used to stream interactions from the browser using Miso's Interactions Upload API or to access read-only search and recommendation results for a given user. When using the publishable API key, the requested user_id will need to be hashed to maintain the necessary security compliance. \n\nSpecify your publishable key in the `api_key` query parameter. For example:\n```\nPOST /v1/interactions?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17\n```\n",
"in": "query",
"name": "api_key"
}
}
},
"tags": [
{
"name": "Experiment APIs",
"description": "\nMiso's experiment APIs let you do the A/B testing of your current result with Miso.\n\n### Start an experiment in Dojo.\n\nLogin to the [dojo](https://dojo.askmiso.com) platform.\nCreate an experiment event for you.\n\n### Start running A/B testing in your environment.\n\n#### Implement A/B testing code.\n\nHere's an example in NodeJS. You can also use any programming language of you choice.\n```nodejs\nconst axios = require('axios');\n\nasync function get_user_experiment_info(api_key, experiment_id, user_id) {\n data = {\"user_id\": user_id}\n endpoint = `https://api.askmiso.com/v1/experiments/${experiment_id}/events?api_key=${api_key}`\n return await axios.post(endpoint, data)\n}\n\nconst api_key = ''\nconst experiment_id = \"\"\nlet user_id = 'user_1234' // use to evaluate a treatment for\n\nconst user_experiment_info = get_user_experiment_info(api_key, experiment_id, user_id)\nuser_experiment_info.then((response) => {\n let variant = response.data['variant']\n if (variant['name'] == \"treatment\") {\n // insert code here to show \"treatment\" variant\n } else if (variant['name'] == \"control\") {\n // insert code here to show \"control\" variant\n } else {\n // unexpected variant name. raise error\n throw new Error(`Unexpected variant name ${variant[\"name\"]}`)\n }\n})\n```\n\nIf you implement A/B testing code in FrontEnd, like JavaScript, and are also worried about exploding the secret api_key. You can choose to use anonymous_id with the public_api_key for this API. Here's an example.\n\n```javascript\nconst apiKey = '';\nconst experimentId = '';\nconst anonymous_id = 'user_1234'; // use to evaluate a treatment for\n\nfunction getUserExperimentInfo(apiKey, experimentId, anonymous_id) {\n const data = {\n user_id: anonymous_id\n };\n const url = `https://api.askmiso.com/v1/experiments/${experimentId}/events?api_key=${apiKey}`;\n const options = {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify(data),\n };\n\n return window.fetch(url, options)\n .then((response) => response.json())\n .then((data) => {\n const variantName = data.variant.name;\n if (variantName === `${this.treatmentName}`) {\n // insert code here to show 'treatment' variant\n } else if (variantName === `${this.controlName}`) {\n // insert code here to show 'control' variant\n } else {\n // unexpected variant name, throw error\n throw new Error(`Unexpected variant name: ${variantName}`);\n }\n })\n .catch((error) => console.error(error));\n}\n\ngetUserExperimentInfo(apiKey, experimentId, anonymous_id);\n```\n"
},
{
"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"
},
{
"name": "Product / Content APIs",
"description": "\nMiso's Product / Content APIs let you upload, read, and delete Product / Content records that represent your site's\ncatalog.\n\n### Product / Content records\nMiso analyzes your Product / Content records to provide personalized search and recommendations that connect users\nwith products or content on your site or application.\n\nMuch of Miso's search and personalization capability relies on understanding your catalog in-depth and drawing\ncorrelations between your catalog and your users' consumption or purchasing behaviors. In other words, Miso\ndiscovers that, with high correlation, users who are interested in certain product attributes would also be\ninterested in other products with similar or related attributes. (For simplicity, we will often overload the word\n\"products\" to mean items for purchase if you are an eCommerce business, and content to consume if you are a content\nmarketplace.)\n\nTo fully optimize your search and recommendations, it is important to provide Miso with Product / Content records\nthat are complete and accurate. We define a set of common attributes that capture the basics of most eCommerce and\ncontent media products, such as `title`, `description`, `categories`, `tags`, `material`, `authors`, etc.\n\nIf your products' characteristics cannot be fully captured by these fields, we recommend that you specify\n`custom_attributes`. For Miso, the more complete the product information is, the better its personalized search\nand recommendations become.\n\n"
},
{
"name": "User APIs",
"description": "\nMiso’s User APIs let you upload, read, and delete User records that tell Miso about your site’s unique users and\nvisitors.\n\n### User records\nUser records specify relatively static attributes for a given user, such as their `age`, `gender`, `city`, etc. As a\nrule of thumb, you should put information here that is not already captured in your\n[Interaction records](#tag/Interaction-APIs). For example, *last_bought_product* is probably not needed here because\nMiso already can tell that from the [Interaction records](#tag/Interaction-APIs).\n\nMiso will discover the correlations between a user's attributes and their behaviors on your site. For example, Miso\nmight determine that users of a certain age group tend to be interested in certain products or a certain price\nrange. These insights will be taken into account when predicting users' interests, in particular for new users who\nhave not yet generated many interaction records.\n\nWe define a set of common user attributes for e-Commerce and content media sites. Some of them, such as `name` are\nfor display in the Dojo dashboard only. The rest are for model quality. Most attributes are optional and you don't\nneed to specify them if you don't collect such data. On the other hand, you can specify your custom user attributes\nin the `custom_attributes` field. Miso will analyze custom user attributes to improve the model quality as well.\n\n"
},
{
"name": "Bulk API",
"description": "\nThe Bulk API provides an efficient interface for making multiple Search / Recommendations / Q&A requests in one API\ncall. These requests will be executed concurrently at the Miso side, and returned at once when all of them are finished.\nThis API is particularly useful when you need to invoke multiple Miso APIs to respond to a user request.\nUsing this API, you can batch multiple API calls into one, and significantly save the network round-trip times.\n\n### Request schema\nThe request schema for this API call is as follow:\n```\nPOST /v1/bulk\n{\n \"requests\": [\n {\n \"api_name\": \"search/search\",\n \"body\": { ... }\n },\n {\n \"api_name\": \"recommendation/product_to_product\",\n \"body\": { ... }\n },\n ...\n ]\n}\n```\nEach request object should contain:\n* **api_name**: name of the API you want to access. The name should contain a slash `/`.\nFor example, search/search for search requests, search/autocomplete for autocomplete requests, etc.\n* **body**: the complete request body as if you are making the API request individually.\n\nAny errors in one of the requests will be returned, and will not prevent other requests from being\nexecuted.\n\n### Response Schema\nBulk API endpoint will return the API responses in the same order as they appear in the request.\nFor example, if the Bulk API request is like the following:\n```\nPOST /v1/bulk\n{\n \"requests\": [\n {... request 1 ...},\n {... request 2 ...}\n ]\n}\n``` \n\nThe response will be like:\n```\n{\n \"data\": [\n // response for request 1\n {\n \"error\": false,\n \"status_code\": 200,\n \"body\": { ... }\n },\n // response for request 2\n {\n \"error\": false,\n \"status_code\": 200,\n \"body\": { ... }\n }\n ]\n}\n```\n\nEach response object will contain the following fields:\n* **error**: whether there was an error with the request. You should check this field to determine whether to\nperform error handling.\n* **status_code**: status code of the request.\n* **body**: the response body of the request (as if the request was sent individually).\n\nLet's see a complete example with MovieLens data. The following requests will issue two requests in one API call that \nreturn the `Sci-Fi` movies directed by\n*Ridley Scott*, and *James Cameron* respectively in the first and second responses:\n```\nPOST /v1/bulk\n{\n \"requests\": [\n {\n \"api_name\": \"search/search\",\n \"body\": {\n \"user_id\": \"test_user\",\n \"q\": \"sci-fi\",\n \"fq\": \"custom_attributes.director:\\\"Ridley Scott\\\"\"\n }\n },\n {\n \"api_name\": \"search/search\",\n \"body\": {\n \"user_id\": \"test_user\",\n \"q\": \"sci-fi\",\n \"fq\": \"custom_attributes.director:\\\"James Cameron\\\"\"\n }\n }\n ]\n}\n```\nThe response will be like:\n```\n{\n \"data\": [\n {\n \"error\": false,\n \"status_code\": 200,\n \"body\": {\n \"data\": {\n \"took\": 136,\n \"miso_id\": \"19ab254c-5fb8-11ec-bd48-b20169940af9\",\n \"products\": [\n {\n \"product_id\": \"blade-runner\",\n \"title\": \"Blade Runner (1982)\"\n }\n ],\n \"total\": 6,\n \"start\": 0\n }\n }\n },\n {\n \"error\": false,\n \"status_code\": 200,\n \"body\": {\n \"data\": {\n \"took\": 116,\n \"miso_id\": \"19ab254c-5fb8-11ec-bd48-b20169940af9\",\n \"products\": [\n {\n \"product_id\": \"avatar\",\n \"title\": \"Avatar (2009)\"\n }\n ],\n \"total\": 10,\n \"start\": 0\n }\n }\n }\n ]\n}\n```\n"
},
{
"name": "Ask APIs",
"description": "\nMiso's new Ask API is the next generation of question answering APIs.\nIt is designed to provide accurate and concise answers to your questions\nbased on your existing product documents.\n\nAsk API offers a seamless and effective way to address complex queries in\na near-realtime fasion.\n\nMiso preprocesses your product documents, breaking them into segments.\nWhen a question is received, Miso finds the most related product and segments, then\nsummarize to a concise and informative answer based on the identified segments,\nincluding products related to the question.\n\nPossible use case includes: knowledge base, documentation search, customer support, and more.\n\nTo use the Ask API, you first submit a \"question\" you want to ask.\nQuestion can be any human-readable text. Then a question ID will returned,\nand the question will be processed in the background.\n\nAfter receving question ID, you can then use the question ID to get latest answer\nto the question as it is being compiled.\n\n----\n\nFor example:\n\nIf you want to know about the inner workings of nginx:\n\n```json\n{\n \"question\":\"How nginx works internally?\"\n}\n```\n\nThe API would response with a question id.\n```json\n{\n \"data\": {\n \"question_id\": \"ff4775fa-345e-4d28-91b0-8fb8bf095e6a\"\n },\n \"message\": \"success\"\n}\n```\n\nThen you can send a GET request to `/v1/ask/questions/{question_id}/answer`\nto get the latest answer as it is being compiled and summerized.\nYou can use `answer_stage` and `finished` to check current answer status.\n\nHere's the response of answer API when data is fetched and being verified, before answer is summerized:\n```json\n{\n \"message\": \"success\",\n \"data\": {\n \"question\": \"How nginx works internally?\",\n \"question_id\": \"ff4775fa-345e-4d28-91b0-8fb8bf095e6a\",\n \"parent_question_id\": null,\n \"answer_stage\": \"Verifying possible answers\",\n \"finished\": false,\n \"answer\": \"Verifying possible answers ...\",\n \"sources\": [],\n \"related_resources\": [],\n \"followup_questions\": []\n }\n}\n```\n\nHere's the response when answer is fullly summerized:\n\n```json\n{\n \"message\": \"success\",\n \"data\": {\n \"question\": \"How nginx works internally?\",\n \"question_id\": \"ff4775fa-345e-4d28-91b0-8fb8bf095e6a\",\n \"parent_question_id\": null,\n \"answer_stage\": \"Generating summary\",\n \"finished\": true,\n \"answer\": \"# How does Nginx work internally?\\n\\n## Internal requests [1]\\n\\nNginx differentiates between external and internal requests. External requests...[omitted for simplicity]\",\n \"sources\": [\n {\n \"title\": \"Internal requests\",\n \"product_id\": \"9781788623551\",\n \"child_title\": \"Internal requests\",\n \"child_id\": \"203\",\n \"snippet\": \"Internal requests\\nNginx differentiates external and internal requests.\"\n },\n {\n \"title\": \"5. Nginx Core Architecture\",\n \"product_id\": \"9781484216569\",\n \"child_title\": \"5. Nginx Core Architecture\",\n \"child_id\": \"5\",\n \"snippet\": \"Checks if the client can access of the requested the resource.\\nIt is at this step that Nginx...[omitted]\"\n },\n {\n \"title\": \"2. Managing Nginx\",\n \"product_id\": \"9781785289538\",\n \"child_title\": \"2. Managing Nginx\",\n \"child_id\": \"14\",\n \"snippet\": \"The Nginx connection processing architecture\\nBefore you study...[omitted]\"\n },\n {\n \"title\": \"3. Nginx Core Directives\",\n \"product_id\": \"9781484216569\",\n \"child_title\": \"3. Nginx Core Directives\",\n \"child_id\": \"3\",\n \"snippet\": \"Understanding the Default Configuration\\nThe default configuration...[omitted]\"\n },\n {\n \"title\": \"4. Nginx Modules\",\n \"product_id\": \"9781484216569\",\n \"child_title\": \"4. Nginx Modules\",\n \"child_id\": \"4\",\n \"snippet\": \"Based on the context like HTTP, MAIL, and STREAM, it creates a ...[omitted]\"\n }\n ],\n \"related_resources\": [],\n \"followup_questions\": [\n \"What are the steps involved in processing a request and generating a response in Nginx?\",\n \"How do Nginx modules contribute to the internal workings of Nginx?\"\n ]\n }\n}\n```\n\nRelated product IDs will be returned along with human-readable answer. Related text section in the product will also be quoted.\n\nIf a product has any children, they will also be matched, `child_id` and `child_title` will be included for sources belonging to the product's children.\n\nYou can use `fq` to limit the search scope, for example, to a specific product type or other condition.\n\nIf you only want to search for books (no articles of videos), you can use `fq=type:book` like this:\n```json\n{\n \"question\":\"How nginx works internally?\"\n \"fq\": \"type:book\"\n}\n```\n\nIf you want the answer to contain any other fields, set `source_fl` when submitting the question.\n\n"
}
],
"x-tagGroups": [
{
"name": "Data APIs",
"tags": [
"Interaction APIs",
"Product / Content APIs",
"User APIs"
]
},
{
"name": "Engine APIs",
"tags": [
"Search APIs",
"Recommendation APIs",
"Ask APIs",
"Signal API",
"Bulk API"
]
},
{
"name": "Experiment APIs",
"tags": [
"Experiment APIs"
]
},
{
"name": "Q&A API",
"tags": [
"Q&A APIs"
]
}
],
"servers": [
{
"url": "https://api.askmiso.com"
}
]
}