v1

latestOpenAPI 3.0.22026-08-0426137631.3 KB

Ask APIs

Create a new question

This API is used to submit questions to Miso.

After a question is submitted, a question_id is returned. Then you can use question_id to check the latest status of it's answer as it is being compiled.

post/v1/ask/questions

Request body

user_idstring

The user who made the query. For an anonymous visitor, use anonymous_id instead.

anonymous_idstring

The anonymous visitor who made this query.

user_hashstring

The hash of user_id (or anonymous_id) encrypted by your Secret API Key. user_hash is used to prevent unauthorized API access if you are making API calls with a Publishable API Key

user_type'anonymous' | 'registered' | 'subscriber' | 'free' | 'paid'

The type of user who made the query, used for rate limiting.

fqstring

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

questionstring required

The question for which an answer is requested.

parent_question_idstring uuid

The UUID of the parent question if the current question is a follow-up to a previous question.

yearly_decaynumber

The yearly decay rate for the answer score.

source_flstring[]

A list of fields to be returned for the sources. Any fields in uploaded product can be assigned, including fields in custom_attributes.

If specificed field does not exist, that field will not be included in the result. If you use different schema for custom_attributes across different products, it is possible that not all returned sources has the some fields.

For example, if you include published_at and custom_attributes in source_fl:

{
    "question":"Explain Python GIL",
    "source_fl":["published_at", "custom_attributes.rating"]
}

The answer will contain published_at field for each source:

{
    "message": "success",
    "data": {
        "question": "Explain Python GIL",
        "question_id": "57aeb083-b943-43b1-86ab-b6108788dd50",
        "parent_question_id": null,
        "answer_stage": "Generating summary",
        "finished": true,
        "answer": "# Explain Python GIL\n\n## Why do we need the GIL? [1]\n\nThe GIL is currently an essential part of the CPython...[omitted for simplicity]",
        "sources": [
            {
                "published_at": "2022-05-20T00:00:00+00:00",
                "custom_attributes": {
                    "rating": 4.7
                },
                "product_id": "9781800207721",
                "title": "Multiprocessing – When a Single CPU Core Is Not Enough",
                "child_title": "Multiprocessing – When a Single CPU Core Is Not Enough",
                "child_id": "16",
                "snippet": "Remember the segmentation faults we saw in Chapter 11, ...[omitted]"
            },
            {
                "published_at": "2015-02-26T00:00:00+00:00",
                "custom_attributes": {
                    "rating": 4.3
                },
                "product_id": "9780134034416",
                "title": "5. Concurrency and Parallelism",
                "child_title": "5. Concurrency and Parallelism",
                "child_id": "12",
                "snippet": "<mark>Click here to view code image\n...[omitted]</mark>"
            },
            {
                "published_at": "2020-04-30T00:00:00+00:00",
                "custom_attributes": {
                    "rating": 3.5
                },
                "product_id": "9781492055013",
                "title": "1. Understanding Performant Python",
                "child_title": "1. Understanding Performant Python",
                "child_id": "2",
                "snippet": "<mark>Although it still locks Python into running ...[omitted]</mark>"
            },
            {
                "published_at": "2019-11-15T00:00:00+00:00",
                "custom_attributes": {
                    "rating": 4.2
                },
                "product_id": "9780134854717",
                "title": "7. Concurrency and Parallelism",
                "child_title": "7. Concurrency and Parallelism",
                "child_id": "16",
                "snippet": "<mark>Although Python supports multiple threads of execution...[omitted]</mark>"
            }
        ],
        "related_resources": []
    }
}

related_resource_flstring[]

A list of fields to be returned for the related_resources. Example: ['title', 'url'].

boost_fqstring

Defines a query in Solr syntax that can be used to boost a subset of products to the top of the ranking. 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 will not boost a low performance product only because it matches the boosting query.

cite_startstring

The citation start marker. Example: [ or {

cite_endstring

The citation end marker. Example: ] or }

Response

Successful Response

messagestring

Human-readable message.