QnAMaker Runtime Client
An API for QnAMaker runtime
COMMUNITYAPI KEY0 INSTALLS
OpenAPI Specificationv3.0
{
"swagger": "2.0",
"schemes": [
"https"
],
"host": "azure.local",
"info": {
"description": "An API for QnAMaker runtime",
"title": "QnAMaker Runtime Client",
"version": "4.0",
"x-apisguru-categories": [
"cloud"
],
"x-logo": {
"url": "https://api.apis.guru/v2/cache/logo/https_assets.onestore.ms_cdnfiles_onestorerolling-1606-01000_shell_v3_images_logo_microsoft.png"
},
"x-origin": [
{
"format": "swagger",
"url": "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/specification/cognitiveservices/data-plane/QnAMaker/stable/v4.0/QnAMakerRuntime.json",
"version": "2.0"
}
],
"x-providerName": "azure.com",
"x-serviceName": "cognitiveservices-QnAMakerRuntime",
"x-tags": [
"Azure",
"Microsoft"
]
},
"consumes": [
"application/json"
],
"produces": [
"application/json"
],
"securityDefinitions": {
"auth_key": {
"in": "header",
"name": "Authorization",
"type": "apiKey"
}
},
"security": [
{
"auth_key": []
}
],
"parameters": {
"GenerateAnswerPayload": {
"description": "Post body of the request.",
"in": "body",
"name": "generateAnswerPayload",
"required": true,
"schema": {
"$ref": "#/definitions/QueryDTO"
},
"x-ms-parameter-location": "method",
"x-nullable": true
},
"KbId": {
"description": "Knowledgebase id.",
"in": "path",
"name": "kbId",
"required": true,
"type": "string",
"x-ms-parameter-location": "method",
"x-nullable": false
},
"RuntimeEndpoint": {
"description": "QnA Maker App Service endpoint (for example: https://{qnaservice-hostname}.azurewebsites.net).",
"in": "path",
"name": "RuntimeEndpoint",
"required": true,
"type": "string",
"x-ms-parameter-location": "client",
"x-ms-skip-url-encoding": true
},
"TrainPayload": {
"description": "Post body of the request.",
"in": "body",
"name": "trainPayload",
"required": true,
"schema": {
"$ref": "#/definitions/FeedbackRecordsDTO"
},
"x-ms-parameter-location": "method",
"x-nullable": true
}
},
"paths": {
"/knowledgebases/{kbId}/generateAnswer": {
"post": {
"operationId": "Runtime_GenerateAnswer",
"parameters": [
{
"$ref": "#/parameters/KbId"
},
{
"$ref": "#/parameters/GenerateAnswerPayload"
}
],
"responses": {
"200": {
"description": "GenerateAnswer call response.",
"schema": {
"$ref": "#/definitions/QnASearchResultList"
}
},
"default": {
"description": "Error response.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"summary": "GenerateAnswer call to query the knowledgebase.",
"tags": [
"Knowledgebases"
],
"x-ms-examples": {
"Successful query": {
"parameters": {
"Authorization": "EndpointKey {Primary/Secondary EndpointKey}",
"Content-Type": "application/json",
"RuntimeEndpoint": "{RuntimeEndpoint}",
"generateAnswerPayload": {
"isTest": true,
"question": "qna maker and luis",
"scoreThreshold": 20,
"strictFilters": [
{
"name": "category",
"value": "api"
}
],
"top": 6,
"userId": "sd53lsY="
},
"kbId": "9d091697-fb8c-4ed5-9ac0-35bf8273bfff"
},
"responses": {
"200": {
"body": {
"answers": [
{
"answer": "There is no direct integration of LUIS with QnA Maker. But, in your bot code, you can use LUIS and QnA Maker together.",
"id": 20,
"metadata": [
{
"name": "category",
"value": "api"
}
],
"questions": [
"How can I integrate LUIS with QnA Maker?"
],
"score": 28.54820341616869,
"source": "Custom Editorial"
}
]
},
"headers": {}
}
}
}
}
}
},
"/knowledgebases/{kbId}/train": {
"post": {
"operationId": "Runtime_Train",
"parameters": [
{
"$ref": "#/parameters/KbId"
},
{
"$ref": "#/parameters/TrainPayload"
}
],
"responses": {
"204": {
"description": "HTTP 204 No Content."
},
"default": {
"description": "Error response.",
"schema": {
"$ref": "#/definitions/ErrorResponse"
}
}
},
"summary": "Train call to add suggestions to the knowledgebase.",
"tags": [
"Knowledgebases"
],
"x-ms-examples": {
"Successful query": {
"parameters": {
"Authorization": "EndpointKey {Primary/Secondary Endpoint Key}",
"Content-Type": "application/json",
"RuntimeEndpoint": "{RuntimeEndpoint}",
"kbId": "9d091697-fb8c-4ed5-9ac0-35bf8273bfff",
"trainPayload": {
"feedbackRecords": [
{
"qnaId": 4,
"userId": "sd53lsY=",
"userQuestion": "qna maker with luis"
}
]
}
},
"responses": {
"204": {}
}
}
}
}
}
},
"definitions": {
"ContextDTO": {
"description": "Context associated with Qna.",
"properties": {
"isContextOnly": {
"description": "To mark if a prompt is relevant only with a previous question or not.\ntrue - Do not include this QnA as search result for queries without context\nfalse - ignores context and includes this QnA in search result",
"type": "boolean"
},
"prompts": {
"description": "List of prompts associated with the answer.",
"items": {
"$ref": "#/definitions/PromptDTO"
},
"maxItems": 20,
"type": "array"
}
},
"type": "object"
},
"Error": {
"additionalProperties": false,
"description": "The error object. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.",
"properties": {
"code": {
"$ref": "#/definitions/ErrorCode",
"description": "One of a server-defined set of error codes."
},
"details": {
"description": "An array of details about specific errors that led to this reported error.",
"items": {
"$ref": "#/definitions/Error"
},
"type": "array"
},
"innerError": {
"$ref": "#/definitions/InnerErrorModel",
"description": "An object containing more specific information than the current object about the error."
},
"message": {
"description": "A human-readable representation of the error.",
"type": "string"
},
"target": {
"description": "The target of the error.",
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
},
"ErrorCode": {
"description": "Human readable error code.",
"enum": [
"BadArgument",
"Forbidden",
"NotFound",
"KbNotFound",
"Unauthorized",
"Unspecified",
"EndpointKeysError",
"QuotaExceeded",
"QnaRuntimeError",
"SKULimitExceeded",
"OperationNotFound",
"ServiceError",
"ValidationFailure",
"ExtractionFailure"
],
"type": "string",
"x-ms-enum": {
"modelAsString": true,
"name": "ErrorCodeType"
}
},
"ErrorResponse": {
"additionalProperties": false,
"description": "Error response. As per Microsoft One API guidelines - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses.",
"properties": {
"error": {
"allOf": [
{
"$ref": "#/definitions/Error"
}
],
"description": "The error object."
}
},
"type": "object"
},
"FeedbackRecordDTO": {
"additionalProperties": false,
"description": "Active learning feedback record.",
"properties": {
"qnaId": {
"description": "The qnaId for which the suggested question is provided as feedback.",
"format": "int32",
"type": "integer"
},
"userId": {
"description": "Unique identifier for the user.",
"type": "string"
},
"userQuestion": {
"description": "The suggested question being provided as feedback.",
"maxLength": 1000,
"type": "string"
}
},
"type": "object"
},
"FeedbackRecordsDTO": {
"additionalProperties": false,
"description": "Active learning feedback records.",
"properties": {
"feedbackRecords": {
"description": "List of feedback records.",
"items": {
"$ref": "#/definitions/FeedbackRecordDTO"
},
"maxLength": 1000,
"type": "array"
}
},
"type": "object"
},
"InnerErrorModel": {
"additionalProperties": false,
"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.",
"properties": {
"code": {
"description": "A more specific error code than was provided by the containing error.",
"type": "string"
},
"innerError": {
"$ref": "#/definitions/InnerErrorModel",
"description": "An object containing more specific information than the current object about the error."
}
},
"type": "object"
},
"MetadataDTO": {
"additionalProperties": false,
"description": "Name - value pair of metadata.",
"properties": {
"name": {
"description": "Metadata name.",
"maxLength": 100,
"minLength": 1,
"type": "string"
},
"value": {
"description": "Metadata value.",
"maxLength": 500,
"minLength": 1,
"type": "string"
}
},
"required": [
"name",
"value"
],
"type": "object"
},
"PromptDTO": {
"description": "Prompt for an answer.",
"properties": {
"displayOrder": {
"description": "Index of the prompt - used in ordering of the prompts",
"format": "int32",
"type": "integer"
},
"displayText": {
"description": "Text displayed to represent a follow up question prompt",
"maxLength": 200,
"type": "string"
},
"qna": {
"allOf": [
{
"$ref": "#/definitions/QnADTO"
}
],
"description": "QnADTO - Either QnaId or QnADTO needs to be present in a PromptDTO object"
},
"qnaId": {
"description": "Qna id corresponding to the prompt - if QnaId is present, QnADTO object is ignored.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"QnADTO": {
"additionalProperties": false,
"description": "Q-A object.",
"properties": {
"answer": {
"description": "Answer text",
"maxLength": 25000,
"minLength": 1,
"type": "string"
},
"context": {
"allOf": [
{
"$ref": "#/definitions/ContextDTO"
}
],
"description": "Context of a QnA"
},
"id": {
"description": "Unique id for the Q-A.",
"format": "int32",
"type": "integer"
},
"metadata": {
"description": "List of metadata associated with the answer.",
"items": {
"$ref": "#/definitions/MetadataDTO"
},
"maxLength": 10,
"type": "array"
},
"questions": {
"description": "List of questions associated with the answer.",
"items": {
"type": "string"
},
"maxLength": 100,
"minLength": 1,
"type": "array"
},
"source": {
"description": "Source from which Q-A was indexed. eg. https://docs.microsoft.com/en-us/azure/cognitive-services/QnAMaker/FAQs",
"maxLength": 300,
"type": "string"
}
},
"required": [
"answer",
"questions"
],
"type": "object"
},
"QnASearchResult": {
"additionalProperties": false,
"description": "Represents Search Result.",
"properties": {
"answer": {
"description": "Answer.",
"type": "string"
},
"context": {
"allOf": [
{
"$ref": "#/definitions/ContextDTO"
}
],
"description": "Context object of the QnA",
"type": "object"
},
"id": {
"description": "Id of the QnA result.",
"format": "int32",
"type": "integer"
},
"metadata": {
"description": "List of metadata.",
"items": {
"$ref": "#/definitions/MetadataDTO"
},
"type": "array"
},
"questions": {
"description": "List of questions.",
"items": {
"type": "string"
},
"type": "array"
},
"score": {
"description": "Search result score.",
"type": "number"
},
"source": {
"description": "Source of QnA result.",
"type": "string"
}
},
"type": "object"
},
"QnASearchResultList": {
"additionalProperties": false,
"description": "Represents List of Question Answers.",
"properties": {
"answers": {
"description": "Represents Search Result list.",
"items": {
"$ref": "#/definitions/QnASearchResult"
},
"type": "array"
}
},
"type": "object"
},
"QueryContextDTO": {
"additionalProperties": false,
"description": "Context object with previous QnA's information.",
"properties": {
"previousQnaId": {
"description": "Previous QnA Id - qnaId of the top result.",
"type": "string"
},
"previousUserQuery": {
"description": "Previous user query.",
"type": "string"
}
},
"type": "object"
},
"QueryDTO": {
"additionalProperties": false,
"description": "POST body schema to query the knowledgebase.",
"properties": {
"context": {
"allOf": [
{
"$ref": "#/definitions/QueryContextDTO"
}
],
"description": "Context object with previous QnA's information."
},
"isTest": {
"description": "Query against the test index.",
"type": "boolean"
},
"qnaId": {
"description": "Exact qnaId to fetch from the knowledgebase, this field takes priority over question.",
"type": "string"
},
"question": {
"description": "User question to query against the knowledge base.",
"type": "string"
},
"rankerType": {
"description": "Optional field. Set to 'QuestionOnly' for using a question only Ranker.",
"type": "string"
},
"scoreThreshold": {
"description": "Threshold for answers returned based on score.",
"type": "number"
},
"strictFilters": {
"description": "Find only answers that contain these metadata.",
"items": {
"$ref": "#/definitions/MetadataDTO"
},
"type": "array"
},
"top": {
"description": "Max number of answers to be returned for the question.",
"format": "int32",
"type": "integer"
},
"userId": {
"description": "Unique identifier for the user.",
"type": "string"
}
},
"type": "object"
}
},
"x-ms-parameterized-host": {
"hostTemplate": "{RuntimeEndpoint}/qnamaker",
"parameters": [
{
"$ref": "#/parameters/RuntimeEndpoint"
}
],
"useSchemePrefix": false
}
}