The Microsoft Azure QnA Maker Runtime Client is a software tool that allows developers to integrate question and answer functionality into their applications. This tool uses natural language processing to interpret user queries and provide accurate responses based on pre-defined knowledge bases. Developers can easily customize and train the QnA Maker Runtime Client to better understand user intent and provide more accurate answers over time.
swagger: '2.0'
info:
version: '4.0'
title: Microsoft Azure QnAMaker Runtime Client
description: An API for QnAMaker runtime
securityDefinitions:
auth_key:
type: apiKey
name: Authorization
in: header
security:
- auth_key: []
x-ms-parameterized-host:
hostTemplate: '{RuntimeEndpoint}/qnamaker'
useSchemePrefix: false
parameters:
- $ref: '#/parameters/RuntimeEndpoint'
paths:
/knowledgebases/{kbId}/generateAnswer:
post:
tags:
- Knowledgebases
summary: 'Microsoft Azure Generateanswer Call To Query The Knowledgebase'
operationId: microsoftAzureRuntimeGenerateanswer
parameters:
- $ref: '#/parameters/KbId'
- $ref: '#/parameters/GenerateAnswerPayload'
consumes:
- application/json
produces:
- application/json
responses:
'200':
description: GenerateAnswer call response.
schema:
$ref: '#/definitions/QnASearchResultList'
default:
description: Error response.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful query:
$ref: ./examples/SuccessfulGenAns.json
description: Needs a more full description created.
/knowledgebases/{kbId}/train:
post:
tags:
- Knowledgebases
summary: 'Microsoft Azure Train Call To Add Suggestions To The Knowledgebase'
operationId: microsoftAzureRuntimeTrain
parameters:
- $ref: '#/parameters/KbId'
- $ref: '#/parameters/TrainPayload'
consumes:
- application/json
produces:
- application/json
responses:
'204':
description: HTTP 204 No Content.
default:
description: Error response.
schema:
$ref: '#/definitions/ErrorResponse'
x-ms-examples:
Successful query:
$ref: ./examples/SuccessfulTrain.json
description: Needs a more full description created.
definitions:
QnADTO:
type: object
description: Q-A object.
additionalProperties: false
required:
- answer
- questions
properties:
id:
type: integer
description: Unique id for the Q-A.
format: int32
answer:
type: string
description: Answer text
maxLength: 25000
minLength: 1
source:
type: string
description: >-
Source from which Q-A was indexed. eg.
https://docs.microsoft.com/en-us/azure/cognitive-services/QnAMaker/FAQs
maxLength: 300
questions:
type: array
description: List of questions associated with the answer.
maxLength: 100
minLength: 1
items:
type: string
metadata:
type: array
description: List of metadata associated with the answer.
maxLength: 10
items:
$ref: '#/definitions/MetadataDTO'
context:
description: Context of a QnA
allOf:
- $ref: '#/definitions/ContextDTO'
ContextDTO:
type: object
description: Context associated with Qna.
properties:
isContextOnly:
type: boolean
description: >-
To mark if a prompt is relevant only with a previous question or not.
true - Do not include this QnA as search result for queries without
context
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/PromptDTO'
PromptDTO:
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 - if QnaId is present, QnADTO
object is ignored.
format: int32
qna:
description: >-
QnADTO - Either QnaId or QnADTO needs to be present in a PromptDTO
object
allOf:
- $ref: '#/definitions/QnADTO'
displayText:
type: string
description: Text displayed to represent a follow up question prompt
maxLength: 200
MetadataDTO:
type: object
description: Name - value pair of metadata.
additionalProperties: false
required:
- name
- value
properties:
name:
type: string
description: Metadata name.
maxLength: 100
minLength: 1
value:
type: string
description: Metadata value.
maxLength: 500
minLength: 1
ErrorResponse:
type: object
description: >-
Error response. As per Microsoft One API guidelines -
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
additionalProperties: false
properties:
error:
description: The error object.
allOf:
- $ref: '#/definitions/Error'
Error:
type: object
description: >-
The error object. As per Microsoft One API guidelines -
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
additionalProperties: false
required:
- code
properties:
code:
description: One of a server-defined set of error codes.
$ref: '#/definitions/ErrorCode'
message:
type: string
description: A human-readable representation of the error.
target:
type: string
description: The target of the error.
details:
type: array
description: >-
An array of details about specific errors that led to this reported
error.
items:
$ref: '#/definitions/Error'
innerError:
description: >-
An object containing more specific information than the current object
about the error.
$ref: '#/definitions/InnerErrorModel'
ErrorCode:
type: string
description: Human readable error code.
x-ms-enum:
name: ErrorCodeType
modelAsString: true
enum:
- BadArgument
- Forbidden
- NotFound
- KbNotFound
- Unauthorized
- Unspecified
- EndpointKeysError
- QuotaExceeded
- QnaRuntimeError
- SKULimitExceeded
- OperationNotFound
- ServiceError
- ValidationFailure
- ExtractionFailure
InnerErrorModel:
type: object
description: >-
An object containing more specific information about the error. As per
Microsoft One API guidelines -
https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.
additionalProperties: false
properties:
code:
type: string
description: A more specific error code than was provided by the containing error.
innerError:
description: >-
An object containing more specific information than the current object
about the error.
$ref: '#/definitions/InnerErrorModel'
QueryDTO:
type: object
description: POST body schema to query the knowledgebase.
additionalProperties: false
properties:
qnaId:
type: string
description: >-
Exact qnaId to fetch from the knowledgebase, this field takes priority
over question.
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. Optional parameter for telemetry. For
more information, refer <a
href="http://aka.ms/qnamaker-analytics#user-traffic"
target="blank">Analytics and Telemetry</a>.
isTest:
type: boolean
description: Query against the test index.
scoreThreshold:
type: number
description: Threshold for answers returned based on score.
context:
description: Context object with previous QnA's information.
allOf:
- $ref: '#/definitions/QueryContextDTO'
rankerType:
type: string
description: >-
Optional field. Set to 'QuestionOnly' for using a question only
Ranker.
strictFilters:
type: array
description: Find only answers that contain these metadata.
items:
$ref: '#/definitions/MetadataDTO'
strictFiltersCompoundOperationType:
type: string
description: >-
Optional field. Set to OR for using OR as Operation for Strict
Filters.
x-ms-enum:
name: StrictFiltersCompoundOperationType
modelAsString: true
enum:
- AND
- OR
QueryContextDTO:
type: object
description: Context object with previous QnA's information.
additionalProperties: false
properties:
previousQnaId:
type: string
description: Previous QnA Id - qnaId of the top result.
previousUserQuery:
type: string
description: Previous user query.
QnASearchResultList:
type: object
description: Represents List of Question Answers.
additionalProperties: false
properties:
answers:
type: array
description: Represents Search Result list.
items:
$ref: '#/definitions/QnASearchResult'
QnASearchResult:
type: object
description: Represents Search Result.
additionalProperties: false
properties:
questions:
type: array
description: List of questions.
items:
type: string
answer:
type: string
description: Answer.
score:
type: number
description: Search result score.
id:
type: integer
description: Id of the QnA result.
format: int32
source:
type: string
description: Source of QnA result.
metadata:
type: array
description: List of metadata.
items:
$ref: '#/definitions/MetadataDTO'
context:
type: object
description: Context object of the QnA
allOf:
- $ref: '#/definitions/ContextDTO'
FeedbackRecordsDTO:
type: object
description: Active learning feedback records.
additionalProperties: false
properties:
feedbackRecords:
type: array
description: List of feedback records.
maxLength: 1000
items:
$ref: '#/definitions/FeedbackRecordDTO'
FeedbackRecordDTO:
type: object
description: Active learning feedback record.
additionalProperties: false
properties:
userId:
type: string
description: Unique identifier for the user.
userQuestion:
type: string
description: The suggested question being provided as feedback.
maxLength: 1000
qnaId:
type: integer
description: The qnaId for which the suggested question is provided as feedback.
format: int32
parameters:
KbId:
type: string
name: kbId
in: path
required: true
x-nullable: false
description: Knowledgebase id.
x-ms-parameter-location: method
RuntimeEndpoint:
name: RuntimeEndpoint
description: >-
QnA Maker App Service endpoint (for example:
https://{qnaservice-hostname}.azurewebsites.net).
x-ms-parameter-location: client
required: true
type: string
in: path
x-ms-skip-url-encoding: true
GenerateAnswerPayload:
name: generateAnswerPayload
in: body
required: true
schema:
$ref: '#/definitions/QueryDTO'
x-nullable: true
description: Post body of the request.
x-ms-parameter-location: method
TrainPayload:
name: trainPayload
in: body
required: true
schema:
$ref: '#/definitions/FeedbackRecordsDTO'
x-nullable: true
description: Post body of the request.
x-ms-parameter-location: method
tags:
- name: Knowledgebases