Knowledge API

Introduction

You can use the Knowledge API to retrieve FAQ-related information from a knowledge base, including things like the structure of the knowledge base and its feedback data.

This API consists of four sections:

• The Session Management API allows you to bundle requests and set your customer ID for your entire session. This is the technical part of the interface, and its concepts and actions are only of interest to developers.
• The Knowledge Base Operations API lets you explore how many categories your knowledge bases contain, what the categories are, and what specific articles are contained in a knowledge base.
• You can use the FAQ Retrieval API to ask your knowledge base a question and find the answers, and also to find any documents that are related to this question.
• The Feedback API gives users a way to send feedback on how useful the responses were.

API Index

Method	URI	Description
Session Management
PUT	/sessions/new/	Creates a new session
GET	/sessions/{sessionId}	Retrieves information about an existing session by sessionId
POST	/sessions/{sessionId}	Associates a recognized user with a previously started anonymous session
Knowledge Base Operations
GET	/kbs/	Retrieves a list of supported knowledge bases
GET	/kbs/{kbId}	Retrieves information about a specific knowledge base (including supported languages)
GET	/kbs/{kbId}/categories	Returns a list of categories
GET	/kbs/{kbId}/{catId}/documents	Returns all document previews for the specified category
GET	/kbs/{kbId}/top	Returns the top X trending documents
GET	/kbs/{kbId}/documents/{docId}	Returns the full content of the specified document
FAQ retrieval
POST	/kbs/{kbId}/search	Executes a search for the answer to the given query
POST	/kbs/{kbId}/suggestions	IntelliSense
GET	/kbs/{kbId}/documents/{docId}/morelikethis	Returns content that is similar to the content in the specified document
GET	/kbs/{kbId}/spelling	Guesses the correct spelling for the entered query
Feedback
POST	/feedback/{kbId}/noAnswer	Marks a query as not having a valid answer in the knowledge base
POST	/feedback/{kbId}/documents/{docId}/vote	Records the user rating for the document within the query
POST	/feedback/{kbId}/documents/{docId}/advancevote	Register positive vote for one document and negative vote for all other in provided list
PUT	/feedback/{kbId}/documents/{docid}/visit	Increments the counter of the viewed document

Knowledge API request

All knowledge API requests may contain additional URL parameter “locale” for specifying the language which is used for error messages in case of request failure.

Knowledge API response

The body of every response returned by the Knowledge API has a standard high-level structure:

{
    "statusCode": <execution code>,
        "error": {
            "type": <string>,
            "message": <string>
        },
        "response": {
... },
"sessionId" : <string>
}

Field	Type	Mandatory	Description
statusCode	String	Yes	Execution code of the operation. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR}
error	Error	Yes	Detailed information on the error message. Present only if the operation executed was unsuccessfully.
response	complex	No	Response PAYLOAD for the executed operation. This can be missing if an error occurred or if the method has nothing to report after execution (for example, if an object has been deleted).
sessionId	String	No	Actual session ID (either obtained from the sessionId parameter, or auto-generated [if the method has been called without sessionId parameter])

Global Complex Types

SessionInfo Complex Type

Field	Type	Mandatory	Description
agentId	String	No	ID of identified agent
customerId	String	No	ID of identified customer
globalVisitId	String	No	ID of registered global visit
visitId	String	No	ID of identified visit

FilterCondition

Field	Type	Mandatory	Description
field	String	Yes	The name of the field to be filtered. Use customFields.<field_name> for referring to a custom field
operator	String	Yes	The operator for expressing the condition. Valid values are: Operator Type Definition lt unary less than le unary less than or equal to eq unary equals ge unary greater than or equal to gt unary greater than between binary between values
value	String	Yes for unary	Value for comparison in unary conditions (lt, le, eq, ge, gt).
a	String	Yes for binary	Left border for comparison in binary operation (from).
b	String	Yes for binary	Right border for comparison in binary operation (to).

KnowledgeBaseMeta

Field	Type	Description
id	String	Knowledge base ID
name	String	Name of knowledge base
active	boolean	Is this knowledge base active
public	boolean	Is this knowledge base public or private
customFields	CustomFieldMeta	Configuration of custom fields for this knowledge base
languages	Map <String, KbLanguageMeta>	Metadata that describes language-specific settings for all available languages of this knowledge base
description	String	Knowledge base description
access	AccessRuleMeta	Skill-based rules of accessing this knowledgebase
behaviour	BehaviourOptions	Options that describe specific behavior features of knowledge base

KbLanguageMeta

Field	Type	Description
name	String	Name of knowledgebase in this particular language
description	String	Description of knowledgebase in this particular language
defaultFilterConditions	FilterCondition []	Set of conditions that filter results retrieved by QNA in this particular language.
schema	Enum {basic,nlp}	The way which GKS analyzes text in knowledgebase in this particular language. GKS uses Nlp, or natural language processing, to improve retrieving quality. Basic means that GKS utilizes basic elasticsearch functionality during retrieving.
default	boolean	This flag indicates that this particular language is the default language for this knowledge base.

AccessRuleMeta

Field	Type	Description
all	boolean	This flag indicates that the knowledgebase does not restrict access based on skills. Value of true means that GKS will ignore the set of skills in the skills field.
skills	String[]	The set of skills that restrict user access to knowledgebase. Only users with at least one of the listed skills can access the knowledgebase. This restriction takes effect only if the field all contains a value of false.

BehaviourOptions

This type consists of a set of named complex options, each of which describes knowledgebase behavior from a specific point of view. At the moment the only set of options is the faq options set.

BehaviourOptions.faq

Field	Type	Description
outOfDomain	float	Confidence level threshold for casting documents with a low level of relevancy that are obtained from a retrieving selection
numberOfAnswersInPreConfidenceSelection	int	Relevance scores from document count are used to compute a denominator that calculates the confidence for each obtained document selection.
trendingPeriodInDays	int	Period in days for computing trends against user activity.
numberOfAnswers	int	Maximum count of documents in the result selection once QNA retrieving is complete.

CustomFieldMeta

Field	Type	Description
name	String	Field name
type	String	Field type. Enumeration of { string, numeric, datetime } Depending on “type” CustomFieldMeta contains range of additional properties: CustomFieldMeta (type=”datetime”) Field Type Description stringFormat String Format of representation of date. For example: “yyyy-MM-dd HH:mm:ss” CustomFieldMeta (type=”numeric”) Field Type Description stringFormat String Regular expression for value validation minValue Numeric Minimum acceptable value (or null if there are no restriction on minimum value) maxValue Numeric Minimum acceptable value (or null if there are no restriction on maximum value) CustomFieldMeta (type=”string”) Field Type Description regex String Regular expression for value validation
displayName	String	Field display name
defaultValue	String	Field default value

SearchRequest

Field	Type	Required	Description
query	String	Yes	User-typed query string
filters	FilterCondition[]	No	List of filters
categories	String[]	No	Set of categories for filtering documents related to these categories
tags	String[]	No	Set of tags for extra filtering of documents related to these tags