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
POST	/kbs/categories	Get federated 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
Federated knowledge retrieval API
POST	/kbs/search	performs search for documents that are relevant for the given query (searches in all available knowledge base)
POST	/kbs/suggestions	retrieve intelliSense suggestions for all available knowledge bases
POST	/kbs/{kbId}/documents/{docId}/federatedmorelikethis	returns documents with content similar to content of provided document (searches among documents of all available knowledge bases)
POST	/kbs/spelling	guess spelling correction for the entered query on basis of corpus of all available knowledge base
Knowledge retrieval API
POST	/kbs/{kbId}/search	performs search for documents that are relevant for the given query (searches in particular knowledge base)
POST	/kbs/{kbId}/suggestions	retrieve intelliSense suggestions for particular knowledge base
GET	/kbs/{kbId}/documents/{docId}/morelikethis	Returns content that is similar to the content in the specified document
GET	/kbs/{kbId}/spelling	Guesses spelling correction for the entered query on basis of particular knowledge base corpus
POST	/kbs/documents	Browse documents
Feedback API
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
POST	/feedback/unanswered	Saves information about federated search request that had no relevant answer (similar to noAnswer, but for federated search)
POST	/feedback/{kbId}/documents/{docid}/use	Saves information about fact of usage of content of document for answering to user question by agent from agent workspace
PUT	/feedback/vote/{voteId}	Adds comment and user rating to vote, registered by POST /feedback/vote
POST	/feedback/vote/	Registers vote against result of federated search
POST	/feedback/{kbId}/documents/{docId}/rating	Registers user rating of particular document (with optional search context )
PUT	/feedback/interaction	Register of fact of receiving new interaction by agent UI
Agent API
GET	/kbs/langs/{lang}/drafts	Retrieves list of suggested documents from all available knowledge bases
GET	/kbs/{kbId}/drafts	Retrieves list of suggested documents from particular knowledge base
POST	/kbs/{kbId}/drafts	Creates suggested document
GET	/kbs/drafts	Retrieves list of suggested documents from set of knowledge bases
PATCH	/kbs/{kbId}/drafts/{draftId}	Marks suggested document as processed
Agent favorite documents processing
GET	/kbs/documents/langs/{lang}/favorites	Retrieves list of all favorite documents
GET	/kbs/{kbId}/documents/favorites	Retrieves list of favorite documents for particular knowledge base
POST	/kbs/{kbId}/documents/{docId}/favorites	Adds document to favorites
DELETE	/kbs/{kbId}/documents/{docId}/favorites	Removes document from favorites
Other
GET	/kbs/{kbId}/documents/{docId}/rating	Returns document user rating and count of visits

URL identifiers: http://.../res1/{id1}/res2/{id2}...
URL parameters: http://...?{param1}&{param2}

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
_ttl	String	No	Time to live. in form of [n]d, [n]h etc. for example "1h" for one hour. TTL can be configured only from Config Server(In Options - section "general" , parameter "session-ttl"). This parameter can not be used for new session creating, only for retrieving actual _ttl of session.

KnowledgeBaseListRequest

Field	Type	Description
Knowledgebases	[]	List of knowledge base identifiers

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
type	String	knowledge type QNA or ARTICLE
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
defaultLanguage	String	Default language for this particular kb
description	String	Knowledge base description
supportedLanguages	String[]	Available languages for this knowledge base

CustomFieldMeta

Field	Type	Description
name	String	field name
type	String	field type. Enumeration of {string, numeric, datetime}
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 of documents related to these categories
tags	String	No	Set of tags for extra filtering of documents related to these tags
media	String	No	Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved.

FederatedSearchRequest

Field	Type	Required	Description
query	String	Yes	User typed query string
filters	FilterCondition []	No	List of filters
categories	Category	No	Set of categories for filtering of documents related to these categories. Each Category is item of structure: Field Type Description id String category identifier kbId String knowledge base identifier
tags	String	No	Set of tags for extra filtering of documents related to these tags
media	String	No	Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved.
knowledgebases	String []	No	List of knowledge base identifiers for restricting scope of search by particular set of knowledge bases.
Warning!
Please take into account that the "knowledgebases" and "categories" filters are applied using the condition "AND", meaning you could face a situation where you might lose a set of documents that do not match both filter conditions at the same time. The easiest way of avoiding this situation is by using only one filter at a time.

RequestKbCategory

Field	Type	Required	Description
kbId	String	true	Knowledgebase identifier
id	String	true	Category identifier

FederatedSearchRequest

Field	Type	Required	Description
query	String	Yes	User typed query string
filter	FilterCondition []	No	List of filters
categories	RequestKbCategory	No	Set of categories for filtering of documents related to these categories
tags	String	No	Set of tags for extra filtering of documents related to these tags
media	String	No	Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved

KnowledgeBaseListRequest

Field	Type	Required	Description
knowledgebases	String	No	List of knowledgebases to retrieving

DocumentDraftRequest

Field	Type	Required	Description
question	String	Yes	Text of document question
answer	String	Yes	Text of document answer
categories	category

AdvanceVote

Field	Type	Required	Description
likeDocId	String	No	Id of document for registering positive voting this aganst it
selection	String	No	Range of Id of documents for registering negative voting this aganst them. Includes all id of selection, incluting document of positive voting
request	SearchRequest	Yes	Original search request

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 }
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	Category []	No	Set of categories for filtering documents related to these categories. Each Category is item of structure: Field Type Description id String category identifier kbld String knowledge base identifier
tags	String	No	Set of tags for extra filtering of documents related to these tags
media	String	No	Instruction for retrieving documents that relate to a specified media type. Empty value means that documents related to any media type will be retrieved.

RequestKbCategory

Field	Type	Required	Description
kbId	String	true	Knowledgebase identifier
id	String	true	Category identifier

FederatedSearchRequest

Field	Type	Required	Description
query	String	Yes	User typed query string
filters	FilterCondition[]	No	List of filters
categories	RequestKbCategory []	No	Set of categories for filtering of documents related to these categories
tags	String []	No	Set of tags for extra filtering of documents related to these tags
media	String	No	Instruction for retrieving documents, that related to specified medi type. Empty value means that documents related to any media type will be retrieved.

KnowledgeBaseListRequest

Field	Type	Required	Description
knowledgebases	String	No	List of knowledgebases to retrieving

DocumentDraftRequest

Field	Type	Required	Description
question	String	Yes	Text of document question
answer	String	Yes	Text of document answer
categories	Category []

AdvanceVote

Field	Type	Required	Description
likeDocId	String	Yes	Id of document for registering positive voting this aganst it
selection	String	No	Range of Id of documents for registering negative voting this aganst them. Includes all id of selection, incluting document of positive voting.
request	SearchRequest	Yes	Original search request