miso.ai Q&A APIs API
The Q&A APIs API from miso.ai — 3 operation(s) for q&a apis.
OpenAPI Specification
openapi: 3.0.2
info:
title: Miso Ask APIs Q&A APIs API
description: '
# Overview
Miso’s approach to personalization is to train machine learning Engines on three core data sets:
1. Your site’s log of historical and real-time interactions,
2. Your catalog of products and content, and
3. Your users. Miso provides the output of its Engines to you, so you can build search and recommendation
experiences that are personalized down to the individual level (n=1 personalization).
To see how Miso works and explore the power of its Engines, we recommend following
[this tutorial](https://docs.askmiso.com/) to get
started with our Playground data. Integrating your site or application with Miso happens in three basic steps:
1. Upload your data
2. Train your Engines
3. Build search and recommendation experiences with the output of your Engines.
Miso provides two main integration points. The first is your [Dojo Dashboard](https://dojo.askmiso.com/),
which is used to set up your Engines with the conversions you want to optimize and your training schedule.
Dojo is also a great way to get familiar with Miso by manually uploading data and exploring the output of
Miso’s Engines. In Dojo’s Sandboxes, you can tweak your Engine settings and see visual examples of Miso’s search
and recommendations running on your live data.
The second integration point is Miso’s API, which lets you automatically manage your data in Miso and build
experiences that leverage the output of Miso’s personalization Engines.
Miso’s API is composed of two major groups of REST API endpoints: Data APIs and Engine APIs.
### Data APIs
Data APIs collect input to Miso''s personalization Engines. These APIs all support high-throughput
data ingestion through bulk insert, and satisfy GDPR and CCPA compliance by letting users delete their data
from Miso. Subcategories of Data APIs are:
* [Interaction APIs](#tag/Interaction-APIs), for managing your Interaction records. By uploading historical and real-time Interaction
records, you tell Miso how users are engaging with the products and content on your site, and in turn, Miso’s
Engines learn how to optimize your conversion funnels.
* [Product / Content APIs](#tag/Product-Content-APIs), for managing your Product / Content records. These records provide a deep semantic
understanding of your catalog and keep Miso up to date about your offerings so it can make smart and timely
suggestions. The `product_id` is how Miso links Product / Content records to your Interaction records.
* [User APIs](#tag/User-APIs), for managing your User records. These records tell Miso about your site’s users and visitors,
so Miso can build an understanding of user segmentation and behavior in relation to products and content.
The `user_id` is how Miso links User records to your Interaction records.
As a rule of thumb, we recommend batching up data to avoid timeout risks. For the Product / Content and User
Upload APIs, we recommend limiting each API upload call to about 100 records at a time. For the Interaction
Upload API, we recommend limiting your calls to around 10,000 records at a time.
### Engine APIs
Engine APIs provide the output of Miso''s personalization Engines. We designed these APIs with a focus on low
latency and high availability. Most of these APIs'' 95th percentile response time is under 75ms,
and the services are replicated to at least three separate instances for high availability.
The types of Engine APIs are:
* [Search APIs](#tag/Search-APIs), for getting Miso’s personalized search results for a user, with search-as-you-type and
autocompletion.
* [Recommendation APIs](#tag/Recommendation-APIs), for retrieving Miso’s recommendations that match users with
the products, categories, and product attributes that are likely to drive conversions.
# Authentication
[View your API Keys in your Dojo Dashboard.](https://dojo.askmiso.com/docs/api-browser)
There are three environments in Miso:
* **Playground**, a read-only tutorial environment with sample data.
* **Development**, for staging, QA, and experimentation.
* **Production**, where you run your live integration with Miso.
Access a Miso environment by passing in the corresponding API key in your API calls. There is one publishable
key and one secret key per environment.
API Key can passed with query parameter `api_key`, or using the `X-API-KEY` header.
'
version: 1.1.4
servers:
- url: https://api.askmiso.com
tags:
- name: Q&A APIs
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: []
/v1/qa/questions:
post:
tags:
- Q&A APIs
summary: Upload Question Bank API
description: "Question Bank API lets you upload your *question bank* to Miso. A *question bank* is a list of questions that\ncan be used for **Question Autocomplete** and **Similar Question Search**.\n\nThis API follows a *replace-all* model, i.e. a successful upload request will replace all the existing questions\nin the question bank.\n\nFor example, the following request will replace the existing question bank with the given three questions:\n```\nPOST /v1/qa/questions\n{\"data\": [\n {\"question\": \"What is python?\"},\n {\"question\": \"What is list comprehension?\"},\n {\"question\": \"How to sort a list in Python?\"}\n]}\n```\n\n\n\n "
operationId: post_questions_v1_qa_questions_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PostQuestionRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/BaseResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
/v1/qa/question_autocomplete:
post:
tags:
- Q&A APIs
summary: Question Autocomplete API
description: "Question Autocomplete is an important feature for Q&A applications. It not only saves your users from typing\nthe complete questions, but also showcases what questions your app is capable answering. This is important because\nQ&A is an advanced search feature that not every user is familar with.\n\nMiso generates autocomplete candidates from the question bank you uploaded (see [Question Bank Upload API](...)).\nGiven a partial question string, Question Autocomplete API will suggest question candidates that match the query\nthe user is typing.\n\n\nFor example, let's first upload three questions to the question bank:\n```\nPOST /v1/qa/questions\n{\"data\": [\n {\"question\": \"What is python?\"},\n {\"question\": \"What is pypy?\"},\n {\"question\": \"How to sort a list in Python?\"}\n]}\n```\n\nThen, immediately after the above request finished, you can send the request below to get autocompletion\ncandidates for any partial query string. For example, if the query string the user types so far is *\"what is p\"*:\n\n```\nPOST /v1/qa/question_autocomplete\n{\n \"q\": \"what is p\",\n \"rows\": 5\n}\n```\n\nThe API will respond the completion candidates like the following:\n```\n{\n \"data\":\n \"completions\": [\n {\"question\": \"What is python?\"},\n {\"question\": \"What is pypy?\"}\n ]\n }\n}\n```\n\nThe API supports adaptive fuzzy matching such that even if there are typos in the query string, the API\nis still able to return the question candidates with the correct spellings. For example, if the query string is\n\"*How to sorta*\". The API is still able to match the completion candidate:\n\"*How to sort a list in Python?*\"\n\nThe API is optimized for instant experience and has an average response time lower than 50ms."
operationId: post_autocomplete_v1_qa_question_autocomplete_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QuestionAutocompleteRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/QAAutocompleteResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- Secret API Key: []
components:
schemas:
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
BaseResponse:
title: BaseResponse
required:
- data
type: object
properties:
message:
title: Message
type: string
default: success
data:
$ref: '#/components/schemas/BaseBody'
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: []
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 `<p>` 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 "
BaseBody:
title: BaseBody
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
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
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
description: Question object
QAResponse:
title: QAResponse
required:
- data
type: object
properties:
message:
title: Message
type: string
default: success
data:
$ref: '#/components/schemas/QAResponseBody'
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: "\nList of fields to retrieve. Each Q&A response, by default, return two fields `answer` and `product_id`, where\n`answer` is an object with the information about the answer paragraph while\n`product_id` identifies the *Product* from which the answer is extracted.\n\nFor example, the following is a sample response from the API:\n```\n{\n \"product_id\": \"ABC-123\",\n \"answer\":\n {\n \"html\": \"<p>Python is an interpreted programming language</p>\",\n \"text\": \"Python is an interpreted programming language\",\n \"css_selector\": \":root > div:nth-child(1) > p:nth-child(2)\",\n \"probability\": 0.99\n }\n}\n```\n\nYou can use `fl` parameter to retrieve additional product fields. For example, the following request\nadditionally retrieves the `title` field for each product along\nwith the `product_id` and `answer`, which are 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 all the `custom_attributes` fields.\n\n```\n{\"fl\": [\"title\", \"custom_attributes.*\"]}\n```\n\nThe following request retrieves all the available product fields:\n\n```\n{\"fl\": [\"*\"]}\n```\n\nFor the lowest latency, use an empty array (which is the default) to retrieve just the `product_id` and `answer` fields.\n```\n{\"fl\": []}\n```\n"
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\n answer paragraph, setting this parameter to `false` will reduce the response size and lower the\n 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: "\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"
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.
'
QAAutocompleteResponseBody:
title: QAAutocompleteResponseBody
required:
- completions
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
completions:
title: Completions
type: array
items:
$ref: '#/components/schemas/app__schemas__engine_api__response__Question'
description: Autocomplete Response
QAAutocompleteResponse:
title: QAAutocompleteResponse
required:
- data
type: object
properties:
message:
title: Message
type: string
default: success
data:
$ref: '#/components/schemas/QAAutocompleteResponseBody'
description: Autocomplete Response
QuestionAutocompleteRequest:
title: QuestionAutocompleteRequest
required:
- q
type: object
properties:
q:
title: Q
minLength: 1
type: string
description: The query user has entered so far
example: what is g
rows:
title: Rows
type: integer
description: Number of autocomplete results to return.
default: 5
description: Post question autocomplete request
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.
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>
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: s
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/misoai/refs/heads/main/openapi/misoai-q-a-apis-api-openapi.yml