openapi: 3.2.0 info: version: v5.0-preview.1 title: Microsoft Azure QnAMaker Client Knowledgebases API description: An API for QnAMaker Service security: - apim_key: [] tags: - name: Knowledge Bases paths: /knowledgebases: get: tags: - Knowledge Bases summary: Microsoft Azure Gets All Knowledgebases For A User operationId: microsoftAzureKnowledgebaseListall responses: '200': description: Collection of knowledgebases. content: application/json: schema: $ref: '#/components/schemas/KnowledgebasesDTO' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulKbsResponse.json description: Needs a more full description created. /knowledgebases/{kbId}: get: tags: - Knowledge Bases summary: Microsoft Azure Gets Details Of A Specific Knowledgebase operationId: microsoftAzureKnowledgebaseGetdetails parameters: - $ref: '#/components/parameters/KbId' responses: '200': description: Details of the knowledgebase. content: application/json: schema: $ref: '#/components/schemas/KnowledgebaseDTO' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulGetKb.json description: Needs a more full description created. delete: tags: - Knowledge Bases summary: Microsoft Azure Deletes The Knowledgebase And All Its Data operationId: microsoftAzureKnowledgebaseDelete parameters: - $ref: '#/components/parameters/KbId' responses: '204': description: HTTP 204 No content. default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulDelKb.json description: Needs a more full description created. post: tags: - Knowledge Bases summary: Microsoft Azure Publishes All Changes In Test Index Of A Knowledgebase To Its… operationId: microsoftAzureKnowledgebasePublish parameters: - $ref: '#/components/parameters/KbId' responses: '204': description: HTTP 204 No content. default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulPubKb.json description: Needs a more full description created. put: tags: - Knowledge Bases summary: Microsoft Azure Replace Knowledgebase Contents operationId: microsoftAzureKnowledgebaseReplace parameters: - $ref: '#/components/parameters/KbId' - $ref: '#/components/parameters/ReplaceKb' responses: '204': description: HTTP 204 No content. default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulRepKb.json description: Needs a more full description created. patch: tags: - Knowledge Bases summary: Microsoft Azure Asynchronous Operation To Modify A Knowledgebase operationId: microsoftAzureKnowledgebaseUpdate parameters: - $ref: '#/components/parameters/KbId' - $ref: '#/components/parameters/UpdateKb' responses: '202': description: Details of the asynchronous operation. headers: Location: description: Relative URI to the target location of the asynchronous operation. Client should poll this resource to get status of the operation. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Operation' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulUpdKb.json description: Needs a more full description created. /knowledgebases/create: post: tags: - Knowledge Bases summary: Microsoft Azure Asynchronous Operation To Create A New Knowledgebase operationId: microsoftAzureKnowledgebaseCreate parameters: - $ref: '#/components/parameters/CreateKbPayload' responses: '202': description: Details of the asynchronous operation. content: application/json: schema: $ref: '#/components/schemas/Operation' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulCreateKb.json description: Needs a more full description created. /knowledgebases/{kbId}/{environment}/qna: get: tags: - Knowledge Bases summary: Microsoft Azure Download The Knowledgebase operationId: microsoftAzureKnowledgebaseDownload parameters: - $ref: '#/components/parameters/KbId' - $ref: '#/components/parameters/Environment' - name: source in: query description: The source property filter to apply. required: false schema: type: string - name: changedSince in: query description: The last changed status property filter to apply. required: false schema: type: string responses: '200': description: Collection of all Q-A in the knowledgebase. content: application/json: schema: $ref: '#/components/schemas/QnADocumentsDTO' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulDownloadKb.json description: Needs a more full description created. /knowledgebases/{kbId}/generateAnswer: post: tags: - Knowledge Bases summary: Microsoft Azure Generateanswer Call To Query Knowledgebase Qna Maker Managed operationId: microsoftAzureKnowledgebaseGenerateanswer parameters: - $ref: '#/components/parameters/KbId' - $ref: '#/components/parameters/GenerateAnswerPayload' responses: '200': description: GenerateAnswer call response. content: application/json: schema: $ref: '#/components/schemas/QnASearchResultList' default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulGenAns.json description: Needs a more full description created. /knowledgebases/{kbId}/train: post: tags: - Knowledge Bases summary: Microsoft Azure Train Call To Add Suggestions To Knowledgebase Qnamaker Managed operationId: microsoftAzureKnowledgebaseTrain parameters: - $ref: '#/components/parameters/KbId' - $ref: '#/components/parameters/TrainPayload' responses: '204': description: HTTP 204 No Content. default: description: Error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-ms-examples: Successful query: $ref: ./examples/SuccessfulTrain.json description: Needs a more full description created. components: schemas: QnASearchResultList: type: object description: Represents List of Question Answers. additionalProperties: false properties: answers: type: array description: Represents Search Result list. items: $ref: '#/components/schemas/QnASearchResult' Operation: type: object description: Record to track long running operation. additionalProperties: false properties: operationState: description: Operation state. $ref: '#/components/schemas/OperationState' createdTimestamp: type: string description: Timestamp when the operation was created. lastActionTimestamp: type: string description: Timestamp when the current state was entered. resourceLocation: type: string description: Relative URI to the target resource location for completed resources. userId: type: string description: User Id operationId: type: string description: Operation Id. errorResponse: description: Error details in case of failures. $ref: '#/components/schemas/ErrorResponse' 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: '#/components/schemas/InnerErrorModel' 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: '#/components/schemas/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: '#/components/schemas/Error' innerError: description: An object containing more specific information than the current object about the error. $ref: '#/components/schemas/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. isTest: type: boolean description: Query against the test index. scoreThreshold: type: number description: Minimum threshold score for answers. context: description: Context object with previous QnA's information. allOf: - $ref: '#/components/schemas/QueryContextDTO' rankerType: type: string description: Optional field. Set to 'QuestionOnly' for using a question only Ranker. strictFilters: type: array description: Find QnAs that are associated with the given list of metadata. items: $ref: '#/components/schemas/MetadataDTO' strictFiltersCompoundOperationType: type: string description: Optional field. Set to 'OR' for using OR operation for strict filters. x-ms-enum: name: StrictFiltersCompoundOperationType modelAsString: true enum: - AND - OR answerSpanRequest: description: To configure Answer span prediction feature. allOf: - $ref: '#/components/schemas/AnswerSpanRequestDTO' ReplaceKbDTO: type: object description: Post body schema for Replace KB operation. additionalProperties: false required: - qnAList properties: qnAList: type: array description: List of Q-A (QnADTO) to be added to the knowledgebase. Q-A Ids are assigned by the service and should be omitted. items: $ref: '#/components/schemas/QnADTO' KnowledgebaseDTO: type: object description: Response schema for CreateKb operation. additionalProperties: false properties: id: type: string description: Unique id that identifies a knowledgebase. hostName: type: string description: URL host name at which the knowledgebase is hosted. lastAccessedTimestamp: type: string description: Time stamp at which the knowledgebase was last accessed (UTC). lastChangedTimestamp: type: string description: Time stamp at which the knowledgebase was last modified (UTC). lastPublishedTimestamp: type: string description: Time stamp at which the knowledgebase was last published (UTC). name: type: string description: Friendly name of the knowledgebase. userId: type: string description: User who created / owns the knowledgebase. urls: type: array description: URL sources from which Q-A were extracted and added to the knowledgebase. items: type: string sources: type: array description: Custom sources from which Q-A were extracted or explicitly added to the knowledgebase. items: type: string QnADocumentsDTO: type: object description: List of QnADTO additionalProperties: false properties: qnaDocuments: type: array description: List of answers. items: $ref: '#/components/schemas/QnADTO' DeleteKbContentsDTO: type: object description: PATCH body schema of Delete Operation in UpdateKb additionalProperties: false properties: ids: type: array description: List of Qna Ids to be deleted items: type: integer format: int32 sources: type: array description: List of sources to be deleted from knowledgebase. maxLength: 300 minLength: 1 items: type: string AnswerSpanResponseDTO: type: object description: Answer span object of QnA. additionalProperties: false properties: text: type: string description: Predicted text of answer span. score: type: number description: Predicted score of answer span. format: double startIndex: type: integer description: Start index of answer span in answer. format: int32 endIndex: type: integer description: End index of answer span in answer. format: int32 UpdateQnaDTO: type: object description: PATCH Body schema for Update Qna List additionalProperties: false properties: id: type: integer description: Unique id for the Q-A format: int32 maximum: 2147483647 minimum: 0 answer: type: string description: Answer text 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: description: List of questions associated with the answer. allOf: - $ref: '#/components/schemas/UpdateQuestionsDTO' metadata: description: List of metadata associated with the answer to be updated allOf: - $ref: '#/components/schemas/UpdateMetadataDTO' context: description: Context associated with Qna to be updated. allOf: - $ref: '#/components/schemas/UpdateContextDTO' UpdateKbContentsDTO: type: object description: PATCH body schema for Update operation in Update Kb additionalProperties: false properties: name: type: string description: Friendly name for the knowledgebase. qnaList: type: array description: List of Q-A (UpdateQnaDTO) to be added to the knowledgebase. items: $ref: '#/components/schemas/UpdateQnaDTO' urls: type: array description: List of existing URLs to be refreshed. The content will be extracted again and re-indexed. maxLength: 10 items: type: string defaultAnswer: type: string description: Default answer sent to user if no good match is found in the KB. maxLength: 300 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: '#/components/schemas/Error' UpdateContextDTO: type: object description: Update Body schema to represent context to be updated properties: promptsToDelete: type: array description: List of prompts associated with qna to be deleted items: type: integer format: int32 promptsToAdd: type: array description: List of prompts to be added to the qna. items: $ref: '#/components/schemas/PromptDTO' 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' UpdateQuestionsDTO: type: object description: PATCH Body schema for Update Kb which contains list of questions to be added and deleted additionalProperties: false properties: add: type: array description: List of questions to be added maxLength: 100 items: type: string delete: type: array description: List of questions to be deleted. maxLength: 100 items: type: string 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: '#/components/schemas/QnADTO' displayText: type: string description: Text displayed to represent a follow up question prompt maxLength: 200 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: '#/components/schemas/MetadataDTO' context: type: object description: Context object of the QnA allOf: - $ref: '#/components/schemas/ContextDTO' answerSpan: type: object description: Answer span object of QnA with respect to user's question. allOf: - $ref: '#/components/schemas/AnswerSpanResponseDTO' 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 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: '#/components/schemas/MetadataDTO' context: description: Context of a QnA allOf: - $ref: '#/components/schemas/ContextDTO' lastUpdatedTimestamp: type: string description: Timestamp when the QnA was last updated. maxLength: 300 CreateKbDTO: type: object description: Post body schema for CreateKb operation. additionalProperties: false required: - name properties: name: type: string description: Friendly name for the knowledgebase. maxLength: 100 minLength: 1 qnaList: type: array description: List of Q-A (QnADTO) to be added to the knowledgebase. Q-A Ids are assigned by the service and should be omitted. maxLength: 1000 items: $ref: '#/components/schemas/QnADTO' urls: type: array description: List of URLs to be used for extracting Q-A. maxLength: 10 items: type: string files: type: array description: List of files from which to Extract Q-A. maxLength: 10 items: $ref: '#/components/schemas/FileDTO' enableHierarchicalExtraction: type: boolean description: Enable hierarchical extraction of Q-A from files and urls. Value to be considered False if this field is not present. defaultAnswerUsedForExtraction: type: string description: Text string to be used as the answer in any Q-A which has no extracted answer from the document but has a hierarchy. Required when EnableHierarchicalExtraction field is set to True. maxLength: 300 minLength: 1 language: type: string description: Language of the knowledgebase. Please find the list of supported languages here. maxLength: 100 minLength: 1 enableMultipleLanguages: type: boolean description: Set to true to enable creating KBs in different languages for the same resource. defaultAnswer: type: string description: Default answer sent to user if no good match is found in the KB. maxLength: 300 minLength: 1 CreateKbInputDTO: type: object description: Input to create KB. additionalProperties: false properties: qnaList: type: array description: List of QNA to be added to the index. Ids are generated by the service and should be omitted. items: $ref: '#/components/schemas/QnADTO' urls: type: array description: List of URLs to be added to knowledgebase. maxLength: 10 items: type: string files: type: array description: List of files to be added to knowledgebase. maxLength: 10 items: $ref: '#/components/schemas/FileDTO' AnswerSpanRequestDTO: type: object description: To configure Answer span prediction feature. additionalProperties: false properties: enable: type: boolean description: Enable or Disable Answer Span prediction. scoreThreshold: type: number format: double description: Minimum threshold score required to include an answer span. topAnswersWithSpan: type: integer description: Number of Top answers to be considered for span prediction. format: int32 maximum: 10 minimum: 1 OperationState: type: string description: Enumeration of operation states. x-ms-enum: name: OperationStateType modelAsString: true enum: - Failed - NotStarted - Running - Succeeded 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 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: '#/components/schemas/PromptDTO' FeedbackRecordsDTO: type: object description: Active learning feedback records. additionalProperties: false properties: feedbackRecords: type: array description: List of feedback records. maxLength: 1000 items: $ref: '#/components/schemas/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 QueryContextDTO: type: object description: Context object with previous QnA's information. additionalProperties: false properties: previousQnaId: type: integer description: Previous QnA Id - qnaId of the top result. previousUserQuery: type: string description: Previous user query. UpdateKbOperationDTO: type: object description: Contains list of QnAs to be updated additionalProperties: false properties: add: description: An instance of CreateKbInputDTO for add operation allOf: - $ref: '#/components/schemas/CreateKbInputDTO' delete: description: An instance of DeleteKbContentsDTO for delete Operation allOf: - $ref: '#/components/schemas/DeleteKbContentsDTO' update: description: An instance of UpdateKbContentsDTO for Update Operation allOf: - $ref: '#/components/schemas/UpdateKbContentsDTO' enableHierarchicalExtraction: type: boolean description: Enable hierarchical extraction of Q-A from files and urls. The value set during KB creation will be used if this field is not present. defaultAnswerUsedForExtraction: type: string description: Text string to be used as the answer in any Q-A which has no extracted answer from the document but has a hierarchy. Required when EnableHierarchicalExtraction field is set to True. maxLength: 300 minLength: 1 FileDTO: type: object description: DTO to hold details of uploaded files. additionalProperties: false required: - fileName - fileUri properties: fileName: type: string description: File name. Supported file types are ".tsv", ".pdf", ".txt", ".docx", ".xlsx". maxLength: 200 minLength: 1 fileUri: type: string description: Public URI of the file. UpdateMetadataDTO: type: object description: PATCH Body schema to represent list of Metadata to be updated additionalProperties: false properties: delete: type: array description: List of Metadata associated with answer to be deleted maxLength: 100 items: $ref: '#/components/schemas/MetadataDTO' add: type: array description: List of metadata associated with answer to be added maxLength: 100 items: $ref: '#/components/schemas/MetadataDTO' KnowledgebasesDTO: type: object description: Collection of knowledgebases owned by a user. additionalProperties: false properties: knowledgebases: type: array description: Collection of knowledgebase records. items: $ref: '#/components/schemas/KnowledgebaseDTO' parameters: GenerateAnswerPayload: name: generateAnswerPayload in: body required: true schema: $ref: '#/components/schemas/QueryDTO' description: Post body of the request. x-ms-parameter-location: method CreateKbPayload: name: createKbPayload in: body required: true schema: $ref: '#/components/schemas/CreateKbDTO' description: Post body of the request. x-ms-parameter-location: method KbId: name: kbId in: path required: true description: Knowledgebase id. x-ms-parameter-location: method schema: type: string TrainPayload: name: trainPayload in: body required: true schema: $ref: '#/components/schemas/FeedbackRecordsDTO' description: Post body of the request. x-ms-parameter-location: method UpdateKb: name: updateKb in: body required: true schema: $ref: '#/components/schemas/UpdateKbOperationDTO' description: Post body of the request. x-ms-parameter-location: method Environment: name: environment in: path required: true description: Specifies whether environment is Test or Prod. x-ms-enum: name: EnvironmentType modelAsString: true x-ms-parameter-location: method schema: type: string enum: - Prod - Test ReplaceKb: name: replaceKb in: body required: true schema: $ref: '#/components/schemas/ReplaceKbDTO' description: An instance of ReplaceKbDTO which contains list of qnas to be uploaded x-ms-parameter-location: method securitySchemes: apim_key: type: apiKey name: Ocp-Apim-Subscription-Key in: header x-ms-parameterized-host: hostTemplate: '{Endpoint}/qnamaker/v5.0-preview.1' useSchemePrefix: false parameters: - $ref: '#/components/parameters/Endpoint'