swagger: '2.0'
info:
  version: 2020-08-01-preview
  title: Microsoft Azure AccessControlClient AccessConnector :Query Knowledgebases API
schemes:
- https
tags:
- name: :Query Knowledgebases
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
definitions:
  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'
  LogicalOperationKind:
    type: string
    description: Set to 'OR' or 'AND' for using corresponding logical operation.
    x-ms-enum:
      name: LogicalOperationKind
      modelAsString: true
    enum:
    - AND
    - OR
  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
  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
  SourceFilter:
    type: array
    description: Find QnAs that are associated with any of the given list of sources in knowledge base.
    items:
      type: string
  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'
  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
  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
  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'
  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.
  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
  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.
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
x-ms-parameterized-host:
  hostTemplate: '{endpoint}'
  useSchemePrefix: false
  parameters:
  - $ref: '#/parameters/Endpoint'