Jump to: navigation, search

Knowledge API


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
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


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).


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


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.


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.


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.


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.


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


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
This page was last modified on August 28, 2015, at 14:42.


Comment on this article:

blog comments powered by Disqus