> ## Documentation Index > Fetch the complete documentation index at: https://docs.miso.ai/llms.txt > Use this file to discover all available pages before exploring further. # Q&A API > Question Answering API analyzes each Product's `html` field and extracts paragraphs that can answer users' questions. For example, Miso can take question likes `What is python?`, and extract an answer like `Python is an interpreted, object-oriented, high-level programming language.` from a product's `html` field. Each answer is assigned a `probability` score that determines how likely a paragraph can accurately answer the question. A probability at least 0.7 is recommended, but you usually will need to fine-tune this threshold to find the precision-and-recall sweet-spot for your application. ### Limitations Miso will only extract answers from the `html` field and from products that have `enable_question_answering` set to `true`. Also, since Q&A is a much more complex search problem, the response time of this API is usually between 1 to 2 seconds for a new question. For an old question this API has answered before, the response time will be less than 75ms. ## OpenAPI ````yaml post /v1/qa/question_answering openapi: 3.0.2 info: title: Miso API description: > # Overview Miso’s approach to personalization is to train machine learning Engines on three core data sets: 1. Your site’s log of historical and real-time interactions, 2. Your catalog of products and content, and 3. Your users. Miso provides the output of its Engines to you, so you can build search and recommendation experiences that are personalized down to the individual level (n=1 personalization). To see how Miso works and explore the power of its Engines, we recommend following [this tutorial](https://docs.askmiso.com/) to get started with our Playground data. Integrating your site or application with Miso happens in three basic steps: 1. Upload your data 2. Train your Engines 3. Build search and recommendation experiences with the output of your Engines. Miso provides two main integration points. The first is your [Dojo Dashboard](https://dojo.askmiso.com/), which is used to set up your Engines with the conversions you want to optimize and your training schedule. Dojo is also a great way to get familiar with Miso by manually uploading data and exploring the output of Miso’s Engines. In Dojo’s Sandboxes, you can tweak your Engine settings and see visual examples of Miso’s search and recommendations running on your live data. The second integration point is Miso’s API, which lets you automatically manage your data in Miso and build experiences that leverage the output of Miso’s personalization Engines. Miso’s API is composed of two major groups of REST API endpoints: Data APIs and Engine APIs. ### Data APIs Data APIs collect input to Miso's personalization Engines. These APIs all support high-throughput data ingestion through bulk insert, and satisfy GDPR and CCPA compliance by letting users delete their data from Miso. Subcategories of Data APIs are: * [Interaction APIs](#tag/Interaction-APIs), for managing your Interaction records. By uploading historical and real-time Interaction records, you tell Miso how users are engaging with the products and content on your site, and in turn, Miso’s Engines learn how to optimize your conversion funnels. * [Product / Content APIs](#tag/Product-Content-APIs), for managing your Product / Content records. These records provide a deep semantic understanding of your catalog and keep Miso up to date about your offerings so it can make smart and timely suggestions. The `product_id` is how Miso links Product / Content records to your Interaction records. * [User APIs](#tag/User-APIs), for managing your User records. These records tell Miso about your site’s users and visitors, so Miso can build an understanding of user segmentation and behavior in relation to products and content. The `user_id` is how Miso links User records to your Interaction records. As a rule of thumb, we recommend batching up data to avoid timeout risks. For the Product / Content and User Upload APIs, we recommend limiting each API upload call to about 100 records at a time. For the Interaction Upload API, we recommend limiting your calls to around 10,000 records at a time. ### Engine APIs Engine APIs provide the output of Miso's personalization Engines. We designed these APIs with a focus on low latency and high availability. Most of these APIs' 95th percentile response time is under 75ms, and the services are replicated to at least three separate instances for high availability. The types of Engine APIs are: * [Search APIs](#tag/Search-APIs), for getting Miso’s personalized search results for a user, with search-as-you-type and autocompletion. * [Recommendation APIs](#tag/Recommendation-APIs), for retrieving Miso’s recommendations that match users with the products, categories, and product attributes that are likely to drive conversions. # Authentication [View your API Keys in your Dojo Dashboard.](https://dojo.askmiso.com/docs/api-browser) There are three environments in Miso: * **Playground**, a read-only tutorial environment with sample data. * **Development**, for staging, QA, and experimentation. * **Production**, where you run your live integration with Miso. Access a Miso environment by passing in the corresponding API key in your API calls. There is one publishable key and one secret key per environment. API Key can passed with query parameter `api_key`, or using the `X-API-KEY` header. version: 1.1.4 servers: - url: https://api.askmiso.com security: [] tags: - name: Experiment APIs description: > Miso's experiment APIs let you do the A/B testing of your current result with Miso. ### Start an experiment in Dojo. Login to the [dojo](https://dojo.askmiso.com) platform. Create an experiment event for you. ### Start running A/B testing in your environment. #### Implement A/B testing code. Here's an example in NodeJS. You can also use any programming language of you choice. ```nodejs const axios = require('axios'); async function get_user_experiment_info(api_key, experiment_id, user_id) { data = {"user_id": user_id} endpoint = `https://api.askmiso.com/v1/experiments/${experiment_id}/events?api_key=${api_key}` return await axios.post(endpoint, data) } const api_key = '' const experiment_id = "" let user_id = 'user_1234' // use to evaluate a treatment for const user_experiment_info = get_user_experiment_info(api_key, experiment_id, user_id) user_experiment_info.then((response) => { let variant = response.data['variant'] if (variant['name'] == "treatment") { // insert code here to show "treatment" variant } else if (variant['name'] == "control") { // insert code here to show "control" variant } else { // unexpected variant name. raise error throw new Error(`Unexpected variant name ${variant["name"]}`) } }) ``` If 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. ```javascript const apiKey = ''; const experimentId = ''; const anonymous_id = 'user_1234'; // use to evaluate a treatment for function getUserExperimentInfo(apiKey, experimentId, anonymous_id) { const data = { user_id: anonymous_id }; const url = `https://api.askmiso.com/v1/experiments/${experimentId}/events?api_key=${apiKey}`; const options = { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(data), }; return window.fetch(url, options) .then((response) => response.json()) .then((data) => { const variantName = data.variant.name; if (variantName === `${this.treatmentName}`) { // insert code here to show 'treatment' variant } else if (variantName === `${this.controlName}`) { // insert code here to show 'control' variant } else { // unexpected variant name, throw error throw new Error(`Unexpected variant name: ${variantName}`); } }) .catch((error) => console.error(error)); } getUserExperimentInfo(apiKey, experimentId, anonymous_id); ``` - name: Interaction APIs description: >+ Miso’s Interaction APIs let you manage your Interaction records stored with Miso. ### Interaction records Your Interaction records tell Miso about user interactions with products and content on your site or application. From these interactions, Miso understands how users move through your conversion funnels: which products or content assets attract the attention of each individual user, and which products or content ultimately will be purchased or consumed by each of them. With these insights, Miso makes real-time tailored recommendations for each user, and responds to each of their clicks and views on the site (even for anonymous users). Interaction records share some common attributes, but are distinguished by their type. Miso captures 23 different interaction types, divided into the following 6 groups: #### Core click-streams * `product_detail_page_view`: a user viewed the detail page for a product * `search`: a user made a search request with keywords and (optionally) filters The above interactions are the core fuel for Miso's personalization Engines, because they happen in a much higher frequency than other interactions and provide an unbiased and high-fidelity view of users' interests on the site. The collection of these interactions is highly important for Miso's personalization performance. At the minimum, you should implement the `product_detail_page_view` interaction to start with. #### Conversion (eCommerce) * `add_to_cart`: a user added a product to the shopping cart * `remove_from_cart`: a user removed a product from the shopping cart * `checkout`: a user checked out and started the payment process * `refund`: a user refunded the product * `subscribe`: a user subscribed to a product The above interactions are the main revenue drivers for eCommerce sites. It’s important to collect them so that Miso can not only drive click-through rates, but actually improve the revenue in a targeted way. To start with, you should at least implement the `add_to_cart` interaction. #### Consumption (content media) * `read`, `watch`, and `listen` interactions capture how and for how long a user consumed a piece of content. * `add_to_collection`: a user added an product to their personal collection * `remove_from_collection`: a user removed an product from their personal collection If you are a content site, the above interactions are the main drivers to users' satisfaction on the site. Collecting these interactions allows Miso to drive consumption rates and consumption durations for the content on your site. If you run a content site, you should implement at least one of these interactions. #### Feedback signals * `like`, `dislike`, `share`, `rate`, and `bookmark` are common ways users express their interests. These are strong signals for Miso to understand each user's preferences regarding your products or content. You should send these signals to Miso if you have any of these UI patterns on your site. #### Performance Checking * `impression`: a user saw or was presented with a product or content asset (but didn't yet interact with it) * `viewable_impression`: the product or content presented is actually viewed by the user (for example, minimum of 50% of the pixels were in viewable space for at least one continuous second.) * `click`: a user clicked on something (for example, a product item) #### Additional click-streams * `home_page_view`: user viewed your home page * `category_page_view`: a user viewed the page for a specific “group” or “family” or products or content in your catalog * `promo_page_view`: user viewed the promotion pages about certain products * `product_image_view`: user clicked on or otherwise interacted with the product image (e.g. enlarged the image) The above interactions are additional signals for Miso to understand users' behavior on the site. #### Custom * `custom` interaction types are reserved for you to define your own business-specific interaction types. Miso will analyze any custom interactions you define to infer users' interests and preferences. - name: Product / Content APIs description: >+ Miso's Product / Content APIs let you upload, read, and delete Product / Content records that represent your site's catalog. ### Product / Content records Miso analyzes your Product / Content records to provide personalized search and recommendations that connect users with products or content on your site or application. Much of Miso's search and personalization capability relies on understanding your catalog in-depth and drawing correlations between your catalog and your users' consumption or purchasing behaviors. In other words, Miso discovers that, with high correlation, users who are interested in certain product attributes would also be interested in other products with similar or related attributes. (For simplicity, we will often overload the word "products" to mean items for purchase if you are an eCommerce business, and content to consume if you are a content marketplace.) To fully optimize your search and recommendations, it is important to provide Miso with Product / Content records that are complete and accurate. We define a set of common attributes that capture the basics of most eCommerce and content media products, such as `title`, `description`, `categories`, `tags`, `material`, `authors`, etc. If your products' characteristics cannot be fully captured by these fields, we recommend that you specify `custom_attributes`. For Miso, the more complete the product information is, the better its personalized search and recommendations become. - name: User APIs description: >+ Miso’s User APIs let you upload, read, and delete User records that tell Miso about your site’s unique users and visitors. ### User records User records specify relatively static attributes for a given user, such as their `age`, `gender`, `city`, etc. As a rule of thumb, you should put information here that is not already captured in your [Interaction records](#tag/Interaction-APIs). For example, *last_bought_product* is probably not needed here because Miso already can tell that from the [Interaction records](#tag/Interaction-APIs). Miso will discover the correlations between a user's attributes and their behaviors on your site. For example, Miso might determine that users of a certain age group tend to be interested in certain products or a certain price range. These insights will be taken into account when predicting users' interests, in particular for new users who have not yet generated many interaction records. We define a set of common user attributes for e-Commerce and content media sites. Some of them, such as `name` are for display in the Dojo dashboard only. The rest are for model quality. Most attributes are optional and you don't need to specify them if you don't collect such data. On the other hand, you can specify your custom user attributes in the `custom_attributes` field. Miso will analyze custom user attributes to improve the model quality as well. - name: Bulk API description: > The Bulk API provides an efficient interface for making multiple Search / Recommendations / Q&A requests in one API call. These requests will be executed concurrently at the Miso side, and returned at once when all of them are finished. This API is particularly useful when you need to invoke multiple Miso APIs to respond to a user request. Using this API, you can batch multiple API calls into one, and significantly save the network round-trip times. ### Request schema The request schema for this API call is as follow: ``` POST /v1/bulk { "requests": [ { "api_name": "search/search", "body": { ... } }, { "api_name": "recommendation/product_to_product", "body": { ... } }, ... ] } ``` Each request object should contain: * **api_name**: name of the API you want to access. The name should contain a slash `/`. For example, search/search for search requests, search/autocomplete for autocomplete requests, etc. * **body**: the complete request body as if you are making the API request individually. Any errors in one of the requests will be returned, and will not prevent other requests from being executed. ### Response Schema Bulk API endpoint will return the API responses in the same order as they appear in the request. For example, if the Bulk API request is like the following: ``` POST /v1/bulk { "requests": [ {... request 1 ...}, {... request 2 ...} ] } ``` The response will be like: ``` { "data": [ // response for request 1 { "error": false, "status_code": 200, "body": { ... } }, // response for request 2 { "error": false, "status_code": 200, "body": { ... } } ] } ``` Each response object will contain the following fields: * **error**: whether there was an error with the request. You should check this field to determine whether to perform error handling. * **status_code**: status code of the request. * **body**: the response body of the request (as if the request was sent individually). Let's see a complete example with MovieLens data. The following requests will issue two requests in one API call that return the `Sci-Fi` movies directed by *Ridley Scott*, and *James Cameron* respectively in the first and second responses: ``` POST /v1/bulk { "requests": [ { "api_name": "search/search", "body": { "user_id": "test_user", "q": "sci-fi", "fq": "custom_attributes.director:\"Ridley Scott\"" } }, { "api_name": "search/search", "body": { "user_id": "test_user", "q": "sci-fi", "fq": "custom_attributes.director:\"James Cameron\"" } } ] } ``` The response will be like: ``` { "data": [ { "error": false, "status_code": 200, "body": { "data": { "took": 136, "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940af9", "products": [ { "product_id": "blade-runner", "title": "Blade Runner (1982)" } ], "total": 6, "start": 0 } } }, { "error": false, "status_code": 200, "body": { "data": { "took": 116, "miso_id": "19ab254c-5fb8-11ec-bd48-b20169940af9", "products": [ { "product_id": "avatar", "title": "Avatar (2009)" } ], "total": 10, "start": 0 } } } ] } ``` - name: Ask APIs description: >+ Miso's new Ask API is the next generation of question answering APIs. It is designed to provide accurate and concise answers to your questions based on your existing product documents. Ask API offers a seamless and effective way to address complex queries in a near-realtime fasion. Miso preprocesses your product documents, breaking them into segments. When a question is received, Miso finds the most related product and segments, then summarize to a concise and informative answer based on the identified segments, including products related to the question. Possible use case includes: knowledge base, documentation search, customer support, and more. To use the Ask API, you first submit a "question" you want to ask. Question can be any human-readable text. Then a question ID will returned, and the question will be processed in the background. After receving question ID, you can then use the question ID to get latest answer to the question as it is being compiled. ---- For example: If you want to know about the inner workings of nginx: ```json { "question":"How nginx works internally?" } ``` The API would response with a question id. ```json { "data": { "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a" }, "message": "success" } ``` Then you can send a GET request to `/v1/ask/questions/{question_id}/answer` to get the latest answer as it is being compiled and summerized. You can use `answer_stage` and `finished` to check current answer status. Here's the response of answer API when data is fetched and being verified, before answer is summerized: ```json { "message": "success", "data": { "question": "How nginx works internally?", "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a", "parent_question_id": null, "answer_stage": "Verifying possible answers", "finished": false, "answer": "Verifying possible answers ...", "sources": [], "related_resources": [], "followup_questions": [] } } ``` Here's the response when answer is fullly summerized: ```json { "message": "success", "data": { "question": "How nginx works internally?", "question_id": "ff4775fa-345e-4d28-91b0-8fb8bf095e6a", "parent_question_id": null, "answer_stage": "Generating summary", "finished": true, "answer": "# How does Nginx work internally?\n\n## Internal requests [1]\n\nNginx differentiates between external and internal requests. External requests...[omitted for simplicity]", "sources": [ { "title": "Internal requests", "product_id": "9781788623551", "child_title": "Internal requests", "child_id": "203", "snippet": "<mark>Internal requests\nNginx differentiates external and internal requests.</mark>" }, { "title": "5. Nginx Core Architecture", "product_id": "9781484216569", "child_title": "5. Nginx Core Architecture", "child_id": "5", "snippet": "Checks if the client can access of the requested the resource.\n<mark>It is at this step that Nginx...[omitted]</mark>" }, { "title": "2. Managing Nginx", "product_id": "9781785289538", "child_title": "2. Managing Nginx", "child_id": "14", "snippet": "<mark>The Nginx connection processing architecture\nBefore you study...[omitted]</mark>" }, { "title": "3. Nginx Core Directives", "product_id": "9781484216569", "child_title": "3. Nginx Core Directives", "child_id": "3", "snippet": "<mark>Understanding the Default Configuration\nThe default configuration...[omitted]</mark>" }, { "title": "4. Nginx Modules", "product_id": "9781484216569", "child_title": "4. Nginx Modules", "child_id": "4", "snippet": "<mark>Based on the context like HTTP, MAIL, and STREAM, it creates a ...[omitted]</mark>" } ], "related_resources": [], "followup_questions": [ "What are the steps involved in processing a request and generating a response in Nginx?", "How do Nginx modules contribute to the internal workings of Nginx?" ] } } ``` Related product IDs will be returned along with human-readable answer. Related text section in the product will also be quoted. If 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. You can use `fq` to limit the search scope, for example, to a specific product type or other condition. If you only want to search for books (no articles of videos), you can use `fq=type:book` like this: ```json { "question":"How nginx works internally?" "fq": "type:book" } ``` If you want the answer to contain any other fields, set `source_fl` when submitting the question. - name: User Recommendations description: >- APIs for recommending products and content to users based on their interests. - name: Product Recommendations description: APIs for recommending related products based on a given product. paths: /v1/qa/question_answering: post: tags: - Q&A APIs summary: Q&A API description: >- Question Answering API analyzes each Product's `html` field and extracts paragraphs that can answer users' questions. For example, Miso can take question likes `What is python?`, and extract an answer like `Python is an interpreted, object-oriented, high-level programming language.` from a product's `html` field. Each answer is assigned a `probability` score that determines how likely a paragraph can accurately answer the question. A probability at least 0.7 is recommended, but you usually will need to fine-tune this threshold to find the precision-and-recall sweet-spot for your application. ### Limitations Miso will only extract answers from the `html` field and from products that have `enable_question_answering` set to `true`. Also, since Q&A is a much more complex search problem, the response time of this API is usually between 1 to 2 seconds for a new question. For an old question this API has answered before, the response time will be less than 75ms. operationId: question_and_answer_v1_qa_question_answering_post requestBody: content: application/json: schema: $ref: '#/components/schemas/QuestionAnsweringRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/QAResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - Secret API Key: [] components: schemas: QuestionAnsweringRequest: title: QuestionAnsweringRequest required: - q - min_probability type: object properties: version: title: Version enum: - v1.2 - v1.3 description: > The model version to use. * **v1.2**: First stable version * **v1.3**: Improve keyword extraction that make answers more precise default: v1.2 example: v1.2 q: title: Q minLength: 1 type: string description: The question user has entered. example: what is gradient descent min_probability: title: Min Probability maximum: 1 minimum: 0 type: number description: > Minimum acceptable probability (between 0.0 and 1.0). The answers whose probability is lower than this number will be excluded from the response. example: 0.7 rows: title: Rows type: integer description: Number of search results to return. default: 1 fl: title: Fl type: array items: type: string description: > List of fields to retrieve. Each Q&A response, by default, return two fields `answer` and `product_id`, where `answer` is an object with the information about the answer paragraph while `product_id` identifies the *Product* from which the answer is extracted. For example, the following is a sample response from the API: ``` { "product_id": "ABC-123", "answer": { "html": "

Python is an interpreted programming language

", "text": "Python is an interpreted programming language", "css_selector": ":root > div:nth-child(1) > p:nth-child(2)", "probability": 0.99 } } ``` You can use `fl` parameter to retrieve additional product fields. For example, the following request additionally retrieves the `title` field for each product along with the `product_id` and `answer`, which are always returned. ``` {"fl": ["title"]} ``` You can also match field names by using `*` as a wildcard. For example, the query below retrieves the `title` and all the `custom_attributes` fields. ``` {"fl": ["title", "custom_attributes.*"]} ``` The following request retrieves all the available product fields: ``` {"fl": ["*"]} ``` For the lowest latency, use an empty array (which is the default) to retrieve just the `product_id` and `answer` fields. ``` {"fl": []} ``` default: [] spellcheck: title: Spellcheck allOf: - $ref: '#/components/schemas/SpellCheckRequest' description: Spellcheck configuration default: enable_auto_spelling_correction: true enable_answer_html: title: Enable Answer Html type: boolean description: >- Whether to return HTML of the answer paragraph. If you don't need the HTML content of the answer paragraph, setting this parameter to `false` will reduce the response size and lower the response latency. default: false enable_answer_block: title: Enable Answer Block type: boolean description: > Whether to return *answer block*. In addition to answer paragraph, Miso can additionally return *answer block*. Answer block is an ancestor HTML node of the answer paragraph that contains the relevant context. The answer block is particularly useful for applications that not only want to show the answer itself but also the **context** surrounding the answer. Answer block is the smallest HTML element that contains the relevant context. However, not all the content inside this node is relevant. You can use the returned `relevant_children_slice` field to identify a portion of this node that is relevant to the answer. default: false fq: title: Fq type: string description: > Defines a query in Solr syntax that can be used to restrict the superset of products to return, without influencing the overall ranking. `fq` can enable users to drill down to products with specific features based on different product attributes For example, the query below limits the search results to only show products whose size is either `M` or `S` and brand is `Nike`: ``` {"fq": "size:(\"M\" OR \"S\") AND brand:\"Nike\""} ``` You can use `fq` to apply filters against your custom attributes as well. For example, the query below limits the search results to only products whose `designer` attribute is `Calvin Klein` ``` {"fq": "attributes.designer:\"Calvin Klein\""} ``` `fq` can also limit search results by numerical range. For example, the following query limits the results to products that have `rating >= 4`. ``` {"fq": "rating:[4 TO *]"} ``` boost_fq: title: Boost Fq type: string description: > Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions* (See `boost_positions` parameter below.) For example, the query below will promote all the relevant products whose brand is `Nike` to the top of recommendation list: ``` { "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE` to the top of the ranking: ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so. First, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3] } ``` The second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 1} } } ``` boost_positions: title: Boost Positions type: array items: type: integer description: > Defines a list of 0-based positions you want to place the boosted products at. For example, the query below will promote products whose brand is `Nike` as the top and second recommendations: ``` { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] } ``` If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. 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: > Define a list of boosting rules that will be applied to the search or recommendation results simultaneously. `boost_rules` parameter is particularly useful when you want to boost more than one sets of products, and promote each of them to different positions. For example, the query below will promote products whose brand is `Nike` to the top and second results, and products whose brand is `Adidas` to the third and fourth results: ``` { "boost_rules": [ { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] }, { "boost_fq": "brand:\"Adidas\"", "boost_positions": [2, 3] } ] } ``` default: [] geo: title: Geo allOf: - $ref: '#/components/schemas/GeoQuery' description: > When set, filter result to include only products within certain geographic range from given point will be returned, or to boost product within the same range. Product should have a field that holds the location of the product, `location` is used by default, but other field can also be used. Distance can be in miles or kilometers. If `distance_unit` is not set, `mile` will be used. For example, to limit results to products within 100 miles of New York city: ``` { "geo": { "filter": [{ "lat": 40.73061, "lon": -73.93524, "distance": 100 }] } } ``` To boost products within 2 kilometers around Alcatraz Island according to `loc` field: ``` { "geo": { "boost": [{ "field": "loc", "lat": 37.82667, "lon": -122.42278, "distance": 2, "distance_unit": "km" }] } } ``` boost_probability_threshold: title: Boost Probability Threshold type: number description: > Minimum probability required for an answer to be boosted. If not specified, the `min_probability` will be used. QAResponse: title: QAResponse required: - data type: object properties: message: title: Message type: string default: success data: $ref: '#/components/schemas/QAResponseBody' HTTPValidationError: title: HTTPValidationError type: object properties: detail: title: Detail type: array items: $ref: '#/components/schemas/ValidationError' SpellCheckRequest: title: SpellCheckRequest type: object properties: enable_auto_spelling_correction: title: Enable Auto Spelling Correction type: boolean description: > This parameter controls whether to automatically correct a misspell search query. If set to `true`, when Miso detects spelling errors, the search results will be based on the **corrected** spelling suggested by Miso. You call tell if Miso made any correction to the search query by checking the `spellcheck.auto_spelling_correction` field in the API response. When this field is `true`, the search results are based on the suggested spelling as opposed to the users' original query. You can opt-out the spelling correction by setting this parameter to `false`. In such cases, Miso will still detect spelling errors, but the search results will be always based on users' original spelling. default: true BoostingFilterBase: title: BoostingFilterBase type: object properties: boost_fq: title: Boost Fq type: string description: > Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking, or to specific *boost positions* (See `boost_positions` parameter below.) For example, the query below will promote all the relevant products whose brand is `Nike` to the top of recommendation list: ``` { "boost_fq": "brand:\"Nike\"" } ``` For a slightly more complex example, the query below will promote the Nike products which have also been tagged as `ON SALE` to the top of the ranking: ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"" } ``` It is worth mentioning that, Miso will only boost products that are relevant and have high likelihood to convert, and will not boost a low performance product only because it matches the boosting query. Depending on your boosting rules, in certain cases, you would like to prevent recommendation results from being too monotone due to boosting. With Miso, you have two tools to do so. First, you can specify `boost_positions` to place promoted products at specific positions in the ranking. For example, the query below will place boosted products only at the first and fourth places in the ranking (positions are 0-based), and place the remaining products in their original ranking, skipping these two positions. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "boost_positions": [0, 3] } ``` The second tool is `diversification`. `diversification` parameter, on a best-effort basis, will try to maintain a minimum distance between products that have the same attributes. For example, the following query will place products made by the same brand apart from each other. ``` { "boost_fq": "brand:\"Nike\" AND tags:\"ON SALE\"", "diversification": { "brand": {"minimum_distance": 1} } } ``` boost_positions: title: Boost Positions type: array items: type: integer description: > Defines a list of 0-based positions you want to place the boosted products at. For example, the query below will promote products whose brand is `Nike` as the top and second recommendations: ``` { "boost_fq": "brand:\"Nike\"", "boost_positions": [0, 1] } ``` If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. 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 GeoQuery: title: GeoQuery type: object properties: filter: title: Filter type: array items: $ref: '#/components/schemas/GeoDistanceQuery' description: >- When set, filter result to include only products within certain geographic range from given point. default: [] boost: title: Boost type: array items: $ref: '#/components/schemas/GeoDistanceQueryBoost' description: >- When set, boost products within certain geographic range from given point. default: [] QAResponseBody: title: QAResponseBody required: - total - spellcheck - answers type: object properties: took: title: Took type: integer description: Number of milliseconds Miso took to retrieve the results. default: 0 miso_id: title: Miso Id type: string description: > Miso-generated unique Id for each recommendation or search result. Maintaining this Id for subsequent page views is important to Miso's performance as we use `miso_id` to track and fine-tune the performance of personalization and search results. When a user clicks on a recommendation or search result, you should pass the associated `miso_id` to the next page view, and associate the `miso_id` with the interactions that take place on the page (e.g. `product_detail_page_view`, `add_to_cart`, `add_to_collection`, `like`, etc.). In this way, Miso will learn which recommendations work and which didn't. Example: ``` {"misoId": "123e4567-e89b-12d3-a456-426614174000"} ``` format: uuid default: 00000000-0000-0000-0000-000000000000 example: 123e4567-e89b-12d3-a456-426614174000 total: title: Total type: integer description: Total number of Question-Answer hits. example: 1000 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. answers: title: Answers type: array items: $ref: '#/components/schemas/RecordWithAnswer' description: The Question-Answer results. 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 GeoDistanceQuery: title: GeoDistanceQuery required: - lat - lon - distance type: object properties: lat: title: Lat maximum: 90 minimum: -90 type: number description: Latitude of the center point, should between 90 and -90 lon: title: Lon maximum: 180 minimum: -180 type: number description: Longitude of the center point, should between 180 and -180 field: title: Field type: string description: >- Name of the field in product data that holds geographic coordinate. Defaults to `location` default: location distance: title: Distance type: number description: >- Distance to center point, in kilometer or mile (according to `distance_unit`) distance_unit: title: Distance Unit enum: - km - mile description: Unit of distance(`km` or `mile`). Defaults to `mile` default: mile GeoDistanceQueryBoost: title: GeoDistanceQueryBoost required: - lat - lon - distance type: object properties: lat: title: Lat maximum: 90 minimum: -90 type: number description: Latitude of the center point, should between 90 and -90 lon: title: Lon maximum: 180 minimum: -180 type: number description: Longitude of the center point, should between 180 and -180 field: title: Field type: string description: >- Name of the field in product data that holds geographic coordinate. Defaults to `location` default: location distance: title: Distance type: number description: >- Distance to center point, in kilometer or mile (according to `distance_unit`) distance_unit: title: Distance Unit enum: - km - mile description: Unit of distance(`km` or `mile`). Defaults to `mile` default: mile boost_positions: title: Boost Positions type: array items: type: integer description: |2- Defines a list of 0-based positions you want to place the boosted products at. If `boost_positions` is not specified (which is the default behavior), all the boosted products will be ranked higher than the rest of the products. 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 <mark> tags example: what is <mark>pythn</mark> 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 <mark> tags. example: what is <mark>python</mark> 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: |2- In addition to the answer paragraph, we also return the **answer block**. Answer block is the ancestor node of the answer paragraph that cover not only the answer, but also the relevant context. This is particularly useful for applications that want to show the answer itself but also the relevant context surrounding the answer. Answer block is the smallest HTML element that contains the relevant context. However, not all the content inside this node is relevant. You can use the `relevant_children_slice` to identify a portion inside this block that is relevant to the answer. Answer: title: Answer required: - probability - text - css_selector type: object properties: probability: title: Probability maximum: 1 minimum: 0 type: number description: >- The probability this paragraph can sufficiently answer the user's question (from 0.0 to 1.0). html: title: Html type: string description: >- The answer paragraph in its original html tag, i.e. or the `outerHTML` of the answer paragraph node. text: title: Text type: string description: The plain text version of answer paragraph. css_selector: title: Css Selector type: string description: > The CSS selector that uniquely identifies the answer paragraph node in the original HTML content. This css selector matches exactly one HTML node that contains the answer paragraph. In order to be as unambiguous as possible, the returned CSS selector is in the form of a series of nth-child selectors starting from `:root` node (which is usually the ``). For example, ``` :root > div:nth-child(1) > p:nth-child(2) ``` . This selector means the answer paragraph is a `

` tag that is the second child of a `

` node, which is in turn, the first child of the `:root` node. This CSS selector is useful when you want to make the answer paragraph stand out from the rest of the document. For example, the following JQuery code turns the background color of the answer paragraph to yellow: ``` $(answer.css_selector).css("background-color", "yellow"); ``` AnswerBlock: title: AnswerBlock required: - html - css_selector - relevant_children_slice - answer_css_selector - title type: object properties: html: title: Html type: string description: The HTML content of the answer block css_selector: title: Css Selector type: string description: >- The CSS selector that uniquely identifies the answer block from the HTML root relevant_children_slice: title: Relevant Children Slice type: array items: type: integer description: >- The range of children nodes inside the *answer block* that is relevant to the selected answer. answer_css_selector: title: Answer Css Selector type: string description: |2- The CSS selector to the selected answer paragraph inside the answer block. You can use this selector to select the answer from the answer block (as supposed to selecting from the HTML root) title: title: Title type: string description: >- The relevant title to the answer paragraph. This title is extracted from a header node close to the answer paragraph. If there is no such node, the title will be an empty string securitySchemes: Secret API Key: type: apiKey description: >+ Your secret API key is used to access every Miso API endpoint. You should secure this key and only use it on a backend server. Never leave this key in your client-side JavaScript code. If the private key is compromised, you can revoke it in [Dojo](https://dojo.askmiso.com/docs/api-browser) and get a new one. Specify your secret key in the `api_key` query parameter. For example: ``` POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17 ``` in: query name: api_key ````