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": "2022-07-01-preview"
  },
  "securityDefinitions": {
    "AADToken": {
      "type": "oauth2",
      "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize",
      "flow": "implicit",
      "description": "These are the [Azure Active Directory OAuth2](https://docs.microsoft.com/azure/active-directory/develop/v1-overview) Flows. When paired with [Azure role-based access](https://docs.microsoft.com/azure/role-based-access-control/overview) control it can be used to control access to Azure Maps REST APIs. Azure role-based access controls are used to designate access to one or more Azure Maps resource account or sub-resources. Any user, group, or service principal can be granted access via a  built-in role or a custom role composed of one or more permissions to Azure Maps REST APIs.\n\nTo implement scenarios, we recommend viewing [authentication concepts](https://aka.ms/amauth). In summary, this security definition provides a solution for modeling application(s) via objects capable of access control on specific APIs and scopes.\n\n#### Notes\n* This security definition **requires** the use of the `x-ms-client-id` header to indicate which Azure Maps resource the application is requesting access to. This can be acquired from the [Maps management API](https://aka.ms/amauthdetails).\n* \nThe `Authorization URL` is specific to the Azure public cloud instance. Sovereign clouds have unique Authorization URLs and Azure Active directory configurations. \n* \nThe Azure role-based access control is configured from the [Azure management plane](https://aka.ms/amrbac) via Azure portal, PowerShell, CLI, Azure SDKs, or REST APIs.\n* \nUsage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for configuration based setup of an application for multiple use cases.\n* Currently, Azure Active Directory [v1.0 or v2.0](https://docs.microsoft.com/azure/active-directory/develop/azure-ad-endpoint-comparison) supports Work, School, and Guests but does not support Personal accounts.",
      "scopes": {
        "https://cognitiveservices.azure.com/.default": "https://cognitiveservices.azure.com/.default"
      }
    },
    "apim_key": {
      "type": "apiKey",
      "name": "Ocp-Apim-Subscription-Key",
      "in": "header"
    }
  },
  "security": [
    {
      "AADToken": [
        "https://cognitiveservices.azure.com/.default"
      ]
    },
    {
      "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"
    }
  }
}