{
  "swagger": "2.0",
  "info": {
    "version": "4.0",
    "title": "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": "GenerateAnswer call to query the knowledgebase.",
        "operationId": "Runtime_GenerateAnswer",
        "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"
          }
        }
      }
    },
    "/knowledgebases/{kbId}/train": {
      "post": {
        "tags": [
          "Knowledgebases"
        ],
        "summary": "Train call to add suggestions to the knowledgebase.",
        "operationId": "Runtime_Train",
        "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"
          }
        }
      }
    }
  },
  "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.\ntrue - Do not include this QnA as search result for queries without context\nfalse - 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"
    }
  }
}