questionanswering.json

{
  "swagger": "2.0",
  "info": {
    "title": "Microsoft Cognitive Language Service - Question Answering",
    "description": "The language service API is a suite of natural language processing (NLP) skills built with best-in-class Microsoft machine learning algorithms.  The API can be used to analyze unstructured text for tasks such as sentiment analysis, key phrase extraction, language detection and question answering. Further documentation can be found in <a href=\"https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview\">https://docs.microsoft.com/en-us/azure/cognitive-services/text-analytics/overview</a>.",
    "version": "2021-10-01"
  },
  "securityDefinitions": {
    "apim_key": {
      "type": "apiKey",
      "name": "Ocp-Apim-Subscription-Key",
      "in": "header"
    }
  },
  "security": [
    {
      "apim_key": []
    }
  ],
  "x-ms-parameterized-host": {
    "hostTemplate": "{Endpoint}/language",
    "useSchemePrefix": false,
    "parameters": [
      {
        "$ref": "common.json#/parameters/Endpoint"
      }
    ]
  },
  "paths": {
    "/:query-knowledgebases": {
      "post": {
        "summary": "Answers the specified question using your knowledge base.",
        "operationId": "QuestionAnswering_GetAnswers",
        "parameters": [
          {
            "$ref": "#/parameters/AnswersOptions"
          },
          {
            "$ref": "common.json#/parameters/ProjectNameQueryParameter"
          },
          {
            "$ref": "common.json#/parameters/DeploymentNameQueryParameter"
          },
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A successful response to get answers from knowledge base.",
            "schema": {
              "$ref": "#/definitions/AnswersResult"
            }
          },
          "default": {
            "description": "Error response.",
            "schema": {
              "$ref": "common.json#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful query": {
            "$ref": "./examples/questionanswering/SuccessfulQueryKnowledgebases.json"
          }
        }
      }
    },
    "/:query-text": {
      "post": {
        "summary": "Answers the specified question using the provided text in the body.",
        "operationId": "QuestionAnswering_GetAnswersFromText",
        "parameters": [
          {
            "$ref": "#/parameters/AnswersFromTextOptions"
          },
          {
            "$ref": "common.json#/parameters/ApiVersionParameter"
          }
        ],
        "consumes": [
          "application/json"
        ],
        "produces": [
          "application/json"
        ],
        "responses": {
          "200": {
            "description": "A successful response to get answers from input text.",
            "schema": {
              "$ref": "#/definitions/AnswersFromTextResult"
            }
          },
          "default": {
            "description": "Error response.",
            "schema": {
              "$ref": "common.json#/definitions/ErrorResponse"
            }
          }
        },
        "x-ms-examples": {
          "Successful query": {
            "$ref": "./examples/questionanswering/SuccessfulQueryText.json"
          }
        }
      }
    }
  },
  "definitions": {
    "AnswersOptions": {
      "type": "object",
      "description": "Parameters to query a knowledge base.",
      "additionalProperties": false,
      "properties": {
        "qnaId": {
          "type": "integer",
          "description": "Exact QnA ID to fetch from the knowledge base, this field takes priority over question.",
          "format": "int32"
        },
        "question": {
          "type": "string",
          "description": "User question to query against the knowledge base."
        },
        "top": {
          "type": "integer",
          "description": "Max number of answers to be returned for the question.",
          "format": "int32"
        },
        "userId": {
          "type": "string",
          "description": "Unique identifier for the user."
        },
        "confidenceScoreThreshold": {
          "type": "number",
          "format": "double",
          "x-ms-client-name": "confidenceThreshold",
          "description": "Minimum threshold score for answers, value ranges from 0 to 1.",
          "maximum": 1,
          "minimum": 0
        },
        "context": {
          "x-ms-client-name": "answerContext",
          "description": "Context object with previous QnA's information.",
          "$ref": "#/definitions/KnowledgeBaseAnswerContext"
        },
        "rankerType": {
          "type": "string",
          "x-ms-client-name": "rankerKind",
          "description": "Type of ranker to be used.",
          "x-ms-enum": {
            "name": "RankerKind",
            "modelAsString": true,
            "values": [
              {
                "value": "QuestionOnly",
                "description": "Question only ranker."
              },
              {
                "value": "Default",
                "description": "Default ranker."
              }
            ]
          },
          "enum": [
            "Default",
            "QuestionOnly"
          ]
        },
        "filters": {
          "description": "Filter QnAs based on given metadata list and knowledge base sources.",
          "$ref": "#/definitions/QueryFilters"
        },
        "answerSpanRequest": {
          "x-ms-client-name": "shortAnswerOptions",
          "description": "To configure Answer span prediction feature.",
          "$ref": "#/definitions/ShortAnswerOptions"
        },
        "includeUnstructuredSources": {
          "type": "boolean",
          "description": "(Optional) Flag to enable Query over Unstructured Sources."
        }
      }
    },
    "ShortAnswerOptions": {
      "type": "object",
      "description": "To configure Answer span prediction feature.",
      "additionalProperties": false,
      "required": [
        "enable"
      ],
      "properties": {
        "enable": {
          "type": "boolean",
          "description": "Enable or disable Answer Span prediction.",
          "enum": [
            true
          ],
          "x-ms-enum": {
            "name": "enable",
            "modelAsString": false
          }
        },
        "confidenceScoreThreshold": {
          "type": "number",
          "format": "double",
          "x-ms-client-name": "confidenceThreshold",
          "description": "Minimum threshold score required to include an answer span, value ranges from 0 to 1.",
          "maximum": 1,
          "minimum": 0
        },
        "topAnswersWithSpan": {
          "type": "integer",
          "x-ms-client-name": "top",
          "description": "Number of Top answers to be considered for span prediction from 1 to 10.",
          "format": "int32",
          "maximum": 10,
          "minimum": 1
        }
      }
    },
    "KnowledgeBaseAnswerContext": {
      "type": "object",
      "description": "Context object with previous QnA's information.",
      "additionalProperties": false,
      "required": [
        "previousQnaId"
      ],
      "properties": {
        "previousQnaId": {
          "type": "integer",
          "description": "Previous turn top answer result QnA ID.",
          "format": "int32"
        },
        "previousUserQuery": {
          "type": "string",
          "x-ms-client-name": "previousQuestion",
          "description": "Previous user query."
        }
      }
    },
    "AnswersResult": {
      "type": "object",
      "description": "Represents List of Question Answers.",
      "additionalProperties": false,
      "properties": {
        "answers": {
          "type": "array",
          "description": "Represents Answer Result list.",
          "items": {
            "$ref": "#/definitions/KnowledgeBaseAnswer"
          }
        }
      }
    },
    "KnowledgeBaseAnswer": {
      "type": "object",
      "description": "Represents knowledge base answer.",
      "additionalProperties": false,
      "properties": {
        "questions": {
          "type": "array",
          "description": "List of questions associated with the answer.",
          "items": {
            "type": "string"
          }
        },
        "answer": {
          "type": "string",
          "description": "Answer text."
        },
        "confidenceScore": {
          "type": "number",
          "format": "double",
          "x-ms-client-name": "confidence",
          "description": "Answer confidence score, value ranges from 0 to 1.",
          "maximum": 1,
          "minimum": 0
        },
        "id": {
          "type": "integer",
          "x-ms-client-name": "qnaId",
          "description": "ID of the QnA result.",
          "format": "int32"
        },
        "source": {
          "type": "string",
          "description": "Source of QnA result."
        },
        "metadata": {
          "type": "object",
          "description": "Metadata associated with the answer, useful to categorize or filter question answers.",
          "additionalProperties": {
            "type": "string"
          }
        },
        "dialog": {
          "type": "object",
          "$ref": "#/definitions/KnowledgeBaseAnswerDialog"
        },
        "answerSpan": {
          "type": "object",
          "x-ms-client-name": "shortAnswer",
          "description": "Answer span object of QnA with respect to user's question.",
          "$ref": "#/definitions/AnswerSpan"
        }
      }
    },
    "KnowledgeBaseAnswerDialog": {
      "type": "object",
      "description": "Dialog associated with Answer.",
      "properties": {
        "isContextOnly": {
          "type": "boolean",
          "description": "To mark if a prompt is relevant only with a previous question or not. If true, do not include this QnA as search result for queries without context; otherwise, if false, ignores context and includes this QnA in search result."
        },
        "prompts": {
          "type": "array",
          "description": "List of prompts associated with the answer.",
          "maxItems": 20,
          "items": {
            "$ref": "#/definitions/KnowledgeBaseAnswerPrompt"
          }
        }
      }
    },
    "KnowledgeBaseAnswerPrompt": {
      "type": "object",
      "description": "Prompt for an answer.",
      "properties": {
        "displayOrder": {
          "type": "integer",
          "description": "Index of the prompt - used in ordering of the prompts.",
          "format": "int32"
        },
        "qnaId": {
          "type": "integer",
          "description": "QnA ID corresponding to the prompt.",
          "format": "int32"
        },
        "displayText": {
          "type": "string",
          "description": "Text displayed to represent a follow up question prompt.",
          "maxLength": 200
        }
      }
    },
    "QueryFilters": {
      "type": "object",
      "description": "filters over knowledge base.",
      "additionalProperties": false,
      "properties": {
        "metadataFilter": {
          "type": "object",
          "$ref": "#/definitions/MetadataFilter"
        },
        "sourceFilter": {
          "type": "object",
          "$ref": "#/definitions/SourceFilter"
        },
        "logicalOperation": {
          "type": "string",
          "description": "Logical operation used to join metadata filter with source filter.",
          "$ref": "#/definitions/LogicalOperationKind",
          "default": "AND"
        }
      }
    },
    "MetadataFilter": {
      "type": "object",
      "description": "Find QnAs that are associated with the given list of metadata.",
      "additionalProperties": false,
      "properties": {
        "metadata": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/MetadataRecord"
          }
        },
        "logicalOperation": {
          "type": "string",
          "description": "Operation used to join metadata filters.",
          "$ref": "#/definitions/LogicalOperationKind",
          "default": "AND"
        }
      }
    },
    "MetadataRecord": {
      "type": "object",
      "description": "Object to provide the key value pair for each metadata.",
      "additionalProperties": false,
      "required": [
        "key",
        "value"
      ],
      "properties": {
        "key": {
          "type": "string",
          "description": "Metadata Key from Metadata dictionary used in the QnA."
        },
        "value": {
          "type": "string",
          "description": "Metadata Value from Metadata dictionary used in the QnA."
        }
      }
    },
    "LogicalOperationKind": {
      "type": "string",
      "description": "Set to 'OR' or 'AND' for using corresponding logical operation.",
      "x-ms-enum": {
        "name": "LogicalOperationKind",
        "modelAsString": true
      },
      "enum": [
        "AND",
        "OR"
      ]
    },
    "SourceFilter": {
      "type": "array",
      "description": "Find QnAs that are associated with any of the given list of sources in knowledge base.",
      "items": {
        "type": "string"
      }
    },
    "AnswerSpan": {
      "type": "object",
      "description": "Answer span object of QnA.",
      "additionalProperties": false,
      "properties": {
        "text": {
          "type": "string",
          "description": "Predicted text of answer span."
        },
        "confidenceScore": {
          "type": "number",
          "x-ms-client-name": "confidence",
          "description": "Predicted score of answer span, value ranges from 0 to 1.",
          "format": "double",
          "maximum": 1,
          "minimum": 0
        },
        "offset": {
          "type": "integer",
          "description": "The answer span offset from the start of answer.",
          "format": "int32"
        },
        "length": {
          "type": "integer",
          "description": "The length of the answer span.",
          "format": "int32"
        }
      }
    },
    "AnswersFromTextOptions": {
      "type": "object",
      "description": "The question and text record parameters to answer.",
      "required": [
        "question",
        "records"
      ],
      "additionalProperties": false,
      "properties": {
        "question": {
          "type": "string",
          "description": "User question to query against the given text records."
        },
        "records": {
          "type": "array",
          "x-ms-client-name": "textDocuments",
          "description": "Text records to be searched for given question.",
          "items": {
            "$ref": "#/definitions/TextDocument"
          }
        },
        "language": {
          "$ref": "common.json#/definitions/Language"
        },
        "stringIndexType": {
          "$ref": "common.json#/definitions/StringIndexType"
        }
      }
    },
    "AnswersFromTextResult": {
      "type": "object",
      "description": "Represents the answer results.",
      "additionalProperties": false,
      "properties": {
        "answers": {
          "type": "array",
          "description": "Represents the answer results.",
          "items": {
            "$ref": "#/definitions/TextAnswer"
          }
        }
      }
    },
    "TextAnswer": {
      "type": "object",
      "description": "Represents answer result.",
      "additionalProperties": false,
      "properties": {
        "answer": {
          "type": "string",
          "description": "Answer."
        },
        "confidenceScore": {
          "type": "number",
          "x-ms-client-name": "confidence",
          "description": "answer confidence score, value ranges from 0 to 1.",
          "format": "double",
          "maximum": 1,
          "minimum": 0
        },
        "id": {
          "type": "string",
          "description": "record ID."
        },
        "answerSpan": {
          "type": "object",
          "x-ms-client-name": "shortAnswer",
          "description": "Answer span object with respect to user's question.",
          "$ref": "#/definitions/AnswerSpan"
        },
        "offset": {
          "type": "integer",
          "description": "The sentence offset from the start of the document.",
          "format": "int32"
        },
        "length": {
          "type": "integer",
          "description": "The length of the sentence.",
          "format": "int32"
        }
      }
    },
    "TextDocument": {
      "type": "object",
      "description": "Represent input text record to be queried.",
      "additionalProperties": false,
      "required": [
        "id",
        "text"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the text record."
        },
        "text": {
          "type": "string",
          "description": "Text contents of the record."
        }
      }
    }
  },
  "parameters": {
    "AnswersOptions": {
      "name": "knowledgeBaseQueryOptions",
      "in": "body",
      "required": true,
      "schema": {
        "$ref": "#/definitions/AnswersOptions"
      },
      "x-nullable": true,
      "description": "Post body of the request.",
      "x-ms-parameter-location": "method"
    },
    "AnswersFromTextOptions": {
      "name": "textQueryOptions",
      "in": "body",
      "required": true,
      "schema": {
        "$ref": "#/definitions/AnswersFromTextOptions"
      },
      "x-nullable": true,
      "description": "Post body of the request.",
      "x-ms-parameter-location": "method"
    }
  }
}