> ## 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. # Product / Content Read API > This API endpoint retrieves the details of a specific product / content using its `product_id`. To fetch the product / content information, make a GET request to the following URL: **Notice**: Make sure the product_id is an urlencode string. ``` GET /v1/products/{product_id} ``` Replace `{product_id}` with the unique identifier of the product / content you wish to fetch. ## Response Format The API will return the product / content details in a JSON object if the given `product_id` is valid and exists in the system. The JSON object will include fields like `title`, `description`, `price`, `images`, and any internationalization fields (`i18n_$LN`). ### Example Response Here's an example of a successful API response for a product / content with the `product_id` "arizona-ginseng-honey": ```json { "product_id": "arizona-ginseng-honey", "title": "Arizona, Green Tea with Ginseng & Honey", "description": "A refreshing and delicious blend of green tea with ginseng and honey.", "price": 1.99, "i18n_es": { "title": "AriZona, Té verde con ginseng y miel" // ... other product details in Spanish }, "i18n_fr": { "title": "AriZona - Thé Vert Aromatisé au Miel" // ... other product details in French }, "i18n_zh": { "title": "美國ARIZONA亞歷桑納 - 蜂蜜人蔘綠茶" // ... other product details in Chinese } } ``` If the provided `product_id` is invalid or does not exist in the system, the API will return an error response with a `status_code=404`. ### Example Error Response ```json { "message": "not found" } ``` ## OpenAPI ````yaml get /v1/products/{product_id} 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": "Internal requests\nNginx differentiates external and internal requests." }, { "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.\nIt is at this step that Nginx...[omitted]" }, { "title": "2. Managing Nginx", "product_id": "9781785289538", "child_title": "2. Managing Nginx", "child_id": "14", "snippet": "The Nginx connection processing architecture\nBefore you study...[omitted]" }, { "title": "3. Nginx Core Directives", "product_id": "9781484216569", "child_title": "3. Nginx Core Directives", "child_id": "3", "snippet": "Understanding the Default Configuration\nThe default configuration...[omitted]" }, { "title": "4. Nginx Modules", "product_id": "9781484216569", "child_title": "4. Nginx Modules", "child_id": "4", "snippet": "Based on the context like HTTP, MAIL, and STREAM, it creates a ...[omitted]" } ], "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. paths: /v1/products/{product_id}: get: tags: - Product / Content APIs summary: Product / Content Read API description: >- This API endpoint retrieves the details of a specific product / content using its `product_id`. To fetch the product / content information, make a GET request to the following URL: **Notice**: Make sure the product_id is an urlencode string. ``` GET /v1/products/{product_id} ``` Replace `{product_id}` with the unique identifier of the product / content you wish to fetch. ## Response Format The API will return the product / content details in a JSON object if the given `product_id` is valid and exists in the system. The JSON object will include fields like `title`, `description`, `price`, `images`, and any internationalization fields (`i18n_$LN`). ### Example Response Here's an example of a successful API response for a product / content with the `product_id` "arizona-ginseng-honey": ```json { "product_id": "arizona-ginseng-honey", "title": "Arizona, Green Tea with Ginseng & Honey", "description": "A refreshing and delicious blend of green tea with ginseng and honey.", "price": 1.99, "i18n_es": { "title": "AriZona, Té verde con ginseng y miel" // ... other product details in Spanish }, "i18n_fr": { "title": "AriZona - Thé Vert Aromatisé au Miel" // ... other product details in French }, "i18n_zh": { "title": "美國ARIZONA亞歷桑納 - 蜂蜜人蔘綠茶" // ... other product details in Chinese } } ``` If the provided `product_id` is invalid or does not exist in the system, the API will return an error response with a `status_code=404`. ### Example Error Response ```json { "message": "not found" } ``` operationId: content_read_api_v1_products__product_id__get parameters: - required: true schema: title: Product Id maxLength: 512 type: string name: product_id in: path responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ProductReadOut' '401': description: Unauthorized content: application/json: example: message: invalid api key. '404': description: Product not Found content: application/json: example: message: not found '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal Server Error content: application/json: example: message: Something went wrong. Please contact miso product team. security: - Secret API Key: [] components: schemas: ProductReadOut: title: ProductReadOut required: - message - data type: object properties: message: title: Message type: string data: $ref: '#/components/schemas/ProductRecord' additionalProperties: false HTTPValidationError: title: HTTPValidationError type: object properties: detail: title: Detail type: array items: $ref: '#/components/schemas/ValidationError' ProductRecord: title: ProductRecord required: - product_id type: object properties: product_id: title: Product Id maxLength: 512 minLength: 1 type: string description: > The unique identifier for this product. The Id can be in any format you use in your product database (e.g. the product's SKU, UPC, or UUID or serial number). We will use this Id to track how users interact with products and content in the Interactions records you upload to Miso. It is important to keep the Id consistent between two datasets. For products that have multiple variants, you should have a unique `product_id` for each variant, and use `product_group_id` to group them together. For example, for a T-shirt with SKU `123ABC` that comes in 4 sizes: `S`, `M`, `L`, `XL`, we should create four different products: ``` { "product_id": "123ABC-S", "product_group_id" "123ABC" } { "product_id": "123ABC-M", "product_group_id" "123ABC" } { "product_id": "123ABC-L", "product_group_id" "123ABC" } { "product_id": "123ABC-XL", "product_group_id" "123ABC" } ``` * Constraints * Can't contain `,` * Can't start with `_` * Length <= 512 example: 123ABC-S-Black product_group_id: title: Product Group Id type: string description: > The `product_group_id` is used to prevent the same product (but a different variant) from showing multiple times in the search or recommendation results. When one product has multiple variants (for example, different sizes, colors, or materials), you should assign a unique product_id to each variant, but assign the same `product_group_id` to all of them. If `product_group_id` is not given, we default to the value of `product_id`. example: 123ABC parent_id: title: Parent Id type: string description: >+ The `parent_id` is used to declare a parent-child relationship between two "Products". Such relationships are common in marketplaces and content media sites with user generated contents. For example, an E-commerce marketplace (such as E-bay or Amazon) may have "Shops" (as parents) and "Merchandises" (as children), and a social streaming site, such as YouTube, may have "Channel" (as parents) and "Video" (as children). In these sites, both entities can be modeled as "Products", and can both be returned in Search and Recommendation APIs. Declaring the parent-child relationships allows Miso to automatically propagate interactions from one product to the other. For example, when a user "watch" a Video, Miso will propagate this signal to the Channel which publishes this Video, even if users do not directly interact with the Channel page. Such implicit interactions are particularly useful when making recommendations for Channel because it gives Miso much more information about users' interests to different Channels than solely relying on users' direct interactions with the them, which happens less often. `parent_id` needs to be a non-empty string referring to the `product_id` of the parent product. The parent product can be uploaded in a separate batch, and does not need to exist before its children products. The implicit interactions will only exist during Miso's training process, and will not show up in the Interaction dataset. example: Nike_Shop_123 related_ids: title: Related Ids type: array items: type: string description: >- The product_id or product_group_id of other products that are related to this Product type: title: Type type: string description: > The `type` of product. This is for sites that have more than one type of product or content that they want their users to interact with. If your site has only one type of product, you can leave this field out. A classic example is travel sites, which have both *hotel* and *flight* sales. It is also useful for sites that let users interact with products as well as *product bundles*. For example, on YouTube, each video is a product that users can watch, while each channel, containing multiple videos, is also a product that users can subscribe to. For model quality, it is preferable to model all these distinct product types in the same data set, so that a user's interests for one type of product can inform their interests in another type of products. The `type` field helps Miso make these distinctions. example: clothes title: title: Title type: string description: > The title of the product. During a search, Miso will put predictive weight behind the title, because it is often the main way users identify a product. example: Japanese Shiba Inu Dog Eating Miso Soup T-Shirt description: title: Description type: string description: > The `description` text of the product. Miso assumes `description` contains longer textual content than other string-based fields. For example, term frequency matters more here than in a field like the title. Miso’s semantic understanding can extract a lot of valuable information from having a product description that is plain-spoken and detailed. example: >- This cute Shiba inu dog eating Miso soup is perfect for those who love Japanese culture. short_description: title: Short Description type: string description: > The `short_description` text of the product. Miso assumes `short_description` contains a shorter version or a summary of the `description` field. example: Cute Shiba Inu Dog Eating Miso Soup T-Shirt language: title: Language minLength: 2 type: string description: > The `language` of the product description and content in [two-letter ISO 639-1 code]( https://en.wikipedia.org/wiki/ISO_639-1). For example, English = `en`, Chinese = `zh`. Miso will use this field to determine the proper way to index the product description. If this field is not specified, we will determine the language automatically. We also use the language field to determine users’ interests in content of different languages. This is particularly important for content media sites that have different languages of content. * Constraints: * [Two-letter ISO 639-1 code](https://en.wikipedia.org/wiki/ISO_639-1). For example, English = `en`, Chinese = `zh`. example: en created_at: title: Created At anyOf: - type: string format: date-time - type: string format: date description: > The time when the product was first created or became available on your site as an ISO-8601 date or datetime string. published_at: title: Published At anyOf: - type: string format: date-time - type: string format: date description: > The time when the product was published as an ISO-8601 date or datetime string. updated_at: title: Updated At anyOf: - type: string format: date-time - type: string format: date description: > The time when the product was updated as an ISO-8601 date or datetime string. categories: title: Categories type: array items: type: array items: type: string description: > In Miso, you describe a product or content category as a hierarchical list of strings from broad to narrow, called a `category`. (See the `category_page_view` interaction.) Use the `categories` field of products to specify the hierarchical category or categories that the product belongs to. A product may belong to only a single `category`, or multiple. For example, a product could be in both: * *Toys & Games > Toys > Dolls, Playsets & Toy Figures > Stuffed Animals*, and * *Arts & Entertainment > Hobbies & Creative Arts > Collectibles*. This field should be a list of a list of strings, where category levels go from broad to narrow, such as: ``` {"categories": [ // the first category the product belongs to ["TOYS & GAMES", "TOYS", "DOLLS, PLAYSETS & TOY FIGURES", "STUFFED ANIMALS"], // the second category the product belongs to ["ARTS & ENTERTAINMENT", "HOBBIES & CREATIVE ARTS", "COLLECTIBLES"] ] } ``` If your product taxonomy has only one single level, that is not an issue: ``` {"categories": [ // the first category the product belongs to ["Toys"], // the second category the product belongs to ["Collectibles"] ] } ``` The categories are optional, but very important for profiling the products and tracking users' preferences. (See also the `category_page_view` interaction) example: - - Clothing, Shoes & Jewelry - Women - T-Shirts - - Novelty - Tops & Tees - T-Shirts tags: title: Tags type: array items: type: string description: | The tags that have been associated with the product. For example: ``` {"tags": ["TAG_1", "TAG_2", ...]} ``` example: - cute - anime - dogs - t-shirt url: title: Url maxLength: 65536 minLength: 1 type: string description: > Url to the product detail page. This is for displaying the product in your Dojo Sandboxes and is not used for Engine training. It is optional, but strongly recommended for a better Sandbox experience. format: uri example: https://example.com/miso-tshirt-123ABC cover_image: title: Cover Image maxLength: 65536 minLength: 1 type: string description: > The URL of the cover image of the product. This is for displaying the product in your Dojo Sandboxes and is not used for Engine training. It is optional, but strongly recommended for a better Sandbox experience. format: uri example: https://example.com/miso-tshirt-123ABC.jpg original_price: title: Original Price type: number description: > The (original) price of the product. We only use this number to calculate the amount of discount, and use that to profile user behaviors. * Constraints: * Need to be a number, but no constraint on the range of the number example: 20 sale_price: title: Sale Price type: number description: | The sale price of the product. * Constraints: * Need to be a number, but no constraint on the range of the number example: 15 margin: title: Margin type: number description: > The margin of the product. Note that for our margin optimization algorithm to work, the margin you specify here does not need to be the actual dollar amount, but it needs to be something in proportion to that. * Constraints: * Need to be a number, but no constraint on the range of the number example: 15 size: title: Size type: string description: > The size of the product. For example, for an eCommerce site that sells T-shirts, each T-shirt might come in several different sizes. In this case, we recommend that you should create one product entry for each size variant. When Miso generate search or recommendation results, we use the `product_group_id` to remove different variants of the same product, and only show the variant that the user is most likely to buy. example: S color: title: Color type: string description: > The color of the products. Similarly to `size`, when `color` of the products matters, it is recommended to create one product for each color variant of a product. When Miso generate search or recommendation results, we use the `product_group_id` to remove variants of the same product, and only show the variant that the user is most likely to buy. example: Black material: title: Material type: string description: > The material of the products. Similarly to `size` and `color`, if `material` of the product matters and there are multiple material variants, we should create one product for each material variant. When Miso generates search or recommendation results, we use the `product_group_id` to remove variants of the same product, and only show the variant that the user is most likely to buy. example: Cotton condition: title: Condition enum: - NEW - USED - REFURBISHED type: string description: > The condition of the product. By default, we assume `condition`= `NEW` default: NEW brand: title: Brand type: string description: | The brand of the product. example: Miso Corp. authors: title: Authors type: array items: type: string description: > The author(s) of the product or content asset. This field needs to be an array of strings. example: - Andy Hsieh publishers: title: Publishers type: array items: type: string description: > The publisher(s) of the product or content asset. This field needs to be an array of strings. example: - O'Reilly Media collections: title: Collections type: array items: type: string description: | The collection(s) the product belongs to. example: - Anime T-Shirt Collection - Superhero T-Shirt Collection availability: title: Availability enum: - IN_STOCK - OUT_OF_STOCK - PRE_ORDER type: string description: > The availability of the product. Miso mainly uses `availability` to filter `OUT_OF_STOCK` items out of its recommendations. As a default, we assume the product is `IN_STOCK`. location: title: Location anyOf: - type: array items: $ref: '#/components/schemas/LocationInformation' - allOf: - $ref: '#/components/schemas/LocationInformation' description: > The location information of the product (e.g. for hotels or restaurants). We support geolocation filtering and sorting when creating search and recommendation results if location information is given. rating: title: Rating type: number description: > The overall rating of the product in the range of [0, 5]. If you use a different rating scale, please convert it to the range of [0, 5]. example: 5 html: title: Html type: string description: > The HTML content of the product. Miso will search against this field and apply semantic understanding in a way that is similar to the `description` field, but with HTML tags removed. subtitle: title: Subtitle type: string description: | The subtitle of the product (usually for contents). headers: title: Headers type: array items: type: string description: > The headers in the content. This usually corresponds to `

`, `

`, `

` ... tags in HTML. This field need to be an array of strings paragraphs: title: Paragraphs type: array items: type: string description: > The text paragraphs in the content. This usually corresponds to `

` tags in HTML. This field need to be an array of strings anchors: title: Anchors type: array items: type: string description: > The anchor texts paragraphs in the content. This usually corresponds to `` tags in HTML. This field need to be an array of strings children: title: Children type: array items: $ref: '#/components/schemas/ChildrenObject' description: > Children objects of the product, such as chapters of a book, or sections of a podcast. Children are only useful for long-form contents, and are only used for snippet extraction purpose. enable_question_answering: title: Enable Question Answering type: boolean description: > Whether to enable question answering capability against the `html` field. default: false 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: object additionalProperties: anyOf: - type: string - type: number - type: integer - type: boolean - type: array items: type: object description: > Dictionary of custom attributes for the product. You can specify attributes specific to your business in a `{"KEY":VALUE}` format, where `KEY` must be a string, and `VALUE` can be: * a `bool` * a `string` or an `array of string` * a `number` or an `array of numbers` * an `array of objects` * `null` For example, a video streaming site using Miso may have the movie *Jumanji* with the following custom attributes: ``` { "custom_attributes": { "cast": [ "Robin Williams", "Jonathan Hyde", ... ], "director": "Joe Johnston", "genres": [ "Adventure", "Fantasy", "Family" ], "filming_locations": [ {"country": "USA", "state": "New Hampshire", "city": "Keene"}, {"country": "Canada", "state": "British Columbia", "city": "Vancouver"} ], "popularity": 7.439, "adult": false } } ``` **The custom attribute types need to be consistent across every record in the dataset**. For instance, in the example above, the **cast** attribute needs to be a `string` or `an array of string` or `null` for every record in the dataset that specify **cast** attribute. Similarly, the popularity attribute needs to be a `number`, `an array of numbers`, or `null` for every record in the dataset that specifies the popularity attribute. If you try to insert a record with an incompatible data type, the insertion for that record will fail. example: cast: - Robin Williams - Jonathan Hyde director: Joe Johnston genres: - Adventure - Fantasy - Family popularity: 7.439 adult: false additionalProperties: false ValidationError: title: ValidationError required: - loc - msg - type type: object properties: loc: title: Location type: array items: type: string msg: title: Message type: string type: title: Error Type type: string LocationInformation: title: LocationInformation required: - lat - lon type: object properties: lat: title: Lat type: number example: 40.74844 lon: title: Lon type: number example: -73.985664 ChildrenObject: title: ChildrenObject required: - id type: object properties: id: title: Id type: string url: title: Url type: string title: title: Title type: string description: title: Description type: string html: title: Html type: string headers: title: Headers type: array items: type: string 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: object additionalProperties: anyOf: - type: string - type: number - type: integer - type: boolean - type: array items: type: object additionalProperties: anyOf: - type: string - type: number - type: integer - type: boolean 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 ````