Q&A API

Authorizations

api_key

string

query

required

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 and get a new one.

Specify your secret key in the api_key query parameter. For example:

POST /v1/users?api_key=039c501ac8dfcac91c6f05601cee876e1cc07e17

Body

application/json

string

required

The question user has entered.

Minimum string length: 1

Example:

"what is gradient descent"

min_probability

number

required

Minimum acceptable probability (between 0.0 and 1.0). The answers whose probability is lower than this number will be excluded from the response.

Required range: 0 <= x <= 1

Example:

0.7

version

enum<string>

default:v1.2

The model version to use.

v1.2: First stable version
v1.3: Improve keyword extraction that make answers more precise

Available options:

v1.2,

v1.3

Example:

"v1.2"

rows

integer

default:1

Number of search results to return.

string[]

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": "<p>Python is an interpreted programming language</p>",
   "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": []}

spellcheck

Spellcheck · object

Spellcheck configuration

Show child attributes

enable_answer_html

boolean

default:false

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.

enable_answer_block

boolean

default:false

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.

string

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

string

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

integer[]

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

string

Name of the boosting rule. Use this to identify a boosting rule in _boosted_rules in the response

boost_rules

BoostingFilterBase · object[]

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]
        }
    ]
}

Show child attributes

geo

Geo · object

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"
        }]
    }
}

Show child attributes

boost_probability_threshold

number

Minimum probability required for an answer to be boosted. If not specified, the min_probability will be used.

Response

Successful Response

data

QAResponseBody · object

required

Show child attributes

message

string

default:success

Overview

Authentication

DATA APIs

Engine APIs

Experiment APIs

Q&A APIs

Limitations

Authorizations

Body

Response