swagger: '2.0'
info:
  title: Microsoft Azure 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: 2023-04-15-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.


      To 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.


      #### Notes

      * 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).

      * 

      The `Authorization URL` is specific to the Azure public cloud instance.
      Sovereign clouds have unique Authorization URLs and Azure Active directory
      configurations. 

      * 

      The 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.

      * 

      Usage of the [Azure Maps Web SDK](https://aka.ms/amaadmc) allows for
      configuration based setup of an application for multiple use cases.

      * 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
    description: A subscription key for a Language service resource.
    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: 'Microsoft Azure Answers The Specified Question Using Your Knowledge Base'
      operationId: microsoftAzureQuestionansweringGetanswers
      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
      description: Needs a more full description created.
      tags:
        - :Query Knowledgebases
  /:query-text:
    post:
      summary: 'Microsoft Azure Answers The Specified Question Using The Provided Text In The Body'
      operationId: microsoftAzureQuestionansweringGetanswersfromtext
      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
      description: Needs a more full description created.
      tags:
        - :Query Text
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
tags:
  - name: :Query Knowledgebases
  - name: :Query Text