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 Analytics and Telemetry. 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