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


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 May 19, 2015, at 02:24.


Comment on this article:

blog comments powered by Disqus