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 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
defaultLanguage	String	Default language for this particular knowledge base
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 } 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