Jump to: navigation, search

Knowledge Base Operations

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.

Authorization

The operations carried out by the Knowledge Base Operations API can be accessed by all roles.

Complex Types

kbId - ID of knowledge base - default value: _dflt that instracts system to use default knowledge base
catId - category Id, default value: _all that instracts system to process request within all categories

ResponseDocumentCategory Complex Type

Field Type Comment
id String category identifier (unique across specific knowledge base)
kbId String knowledge base identifier
name String category verbal identifier

DocumentEntry Complex Type

API - oriented QNA Document representation

Field Type Description
id String Unique document ID
kbId String Knowledge base ID
language String Document language
url String External URL associated with this document
media String[] List of media types associated with this document
tags String[] List of tags associated with this document
categories ResponseDocumentCategory[] List of categories associated with this document
created Date Document creation date, represented as a string in the format of "yyyy-MM-dd HH:mm:ss"
modified Date Document modification date, represented as a string in the format of "yyyy-MM-dd HH:mm:ss"
customFields Map<String, Object> Set of custom field values
question String FAQ question
answer String FAQ answer

ScoredDocumentEntry Complex Type

Field Type Description
All the fields of DocumentEntry
score Float Relevancy score of document against particular search request obtained by core functionality

ConfidentDocumentEntry Complex Type

Field Type Description
All the fields of ScoredDocumentEntry
confidence Float Confidence level of content against particular query

DocumentDraftEntry Complex Type

Field Type Description
id String unique document identifier
categories ResponseDocumentCategory[] list of id of categories, associated with particular document
timestamp Date date of document creation. represented in form of string in format of "yyyy-MM-dd HH:mm:ss"
author String id of agent, who authored document draft
question String question
answer String answer
status String status of document draft (created, accepted, rejected)
documentId String In case if document created on base of draft - id of this document

AuthoredDocumentEntry complex type

Field Type Description
All the fields of DocumentDraftEntry
document DocumentEntry In case if document created on base of draft - this document
lang String Document draft language

Pagination Complex Type

Field Type Description
from int Page offset
size int Page size

List of knowledge bases

Description retrieves list of knowledge bases supported
URL /kbs/
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL IDs None
URL Parameters
Parameter Type Req Default Description
subTenantId String No Sub tenant identifier
lang String No "_default" Language
sessionId String No session identifier
Request empty
Response
Field Type Description
knowledgebases KnowledgeBaseMeta[] List of knowledge bases
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

KnowledgeBaseCategory

Field Type Description
id String unique category identifier
kbId String knowledge base identifier
name String name of category
count String How many documents refers to this category

Get knowledgebase document categories

Description get list of categories
URL /kbs/{kbId}/categories
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
URL Parameters
Parameter Type Req Default Description
lang String No "_default" Language
SubTenantId String No Sub tenant identifier
sessionId String No session identifier
Request empty
Response
Field Type Description
categories KnowledgeBaseCategory[] List of categories for given knowledgebase
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Get federated categories

Description get list of categories
URL /kbs/langs/{lang}/categories
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Identifier Type Description
lang String Language identifier
URL Parameters
Parameter Type Req Default Description
lang String No "_default" Language
SubTenantId String No Sub tenant identifier
sessionId String No session identifier
Request KnowledgeBaseListRequest
Response
Parameter Type Description
categories KnowledgeBaseCategory[] list of categories for given knowledgebase
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Get knowledgebase documents, associated with given category

Description get all document previews in category
URL /kbs/{kbId}/{catId}/documents
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
{catId} String specific category identifier
URL Parameters
Parameter Type Required Default Description
from int No 0 Start position for pagination, default=0
size int No 10 Size of page for pagination, default=10
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request empty
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
page Pagination pagination information
documents DocumentEntry [] result selection of document
categories CategoryFacetItem[] Facet selection of categories, related to selected documents set

Each item of categories has structure (CategoryFacetItem):

Field Type Description
id String id of category
count String count of this particular category id in result selection
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

Get top X trending documents

Description get top X trending documents
URL /kbs/{kbId}/top
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
size int No 10 Size of page for pagination, default=10
sessionId String No Session identifier
Request empty
Response
Field Type Description
count int total count of documents in selection (pagination-independent)
documents DocumentEntry [] result selection of document
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.


Get full content of document

Description get full content of particular document
URL /kbs/{kbId}/documents/{docId}
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL IDentifiers
Parameter Type Description
{kbId} String Knowledgebase identifier
{docId} String Unique document identifier
URL Parameters
Parameter Type Required Default Description
lang String No "_default" Language identifier
subTenantId String No Sub tenant identifier
sessionId String No Session identifier
Request empty
Response DocumentEntry
Notes In case of success returns payload in response field of "response" of declared structure.

In case of error returns code and description of error.

CategoryFacetItem

Field Type Description
id String Category Identifier
kbld String Knowledge base identifier
name String Category name
count int Count of categories with this id in obtained document selection

Retrieve a List of Supported Knowledge Bases

Description Retrieves a list of supported knowledge bases that the user or agent identified by the http header of gkc_agentId may access.
URL /kbs/
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers None
URL Parameters
Parameter Type Req? Default Description
lang String No "_all" Language.

Use _all for retrieving meta information about all knowledge bases, independently of supported language.
Specify particular language for retrieving meta information of knowledge bases that support this language.

sessionId String No Session ID
Request Empty
Response
Field Type Description
knowledgebases KnowledgeBaseMeta List of knowledge bases

Retrieve Knowledge Base Information

Description Retrieves information about a specific knowledge base (including supported languages)
URL /kbs/{kbId}
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL Parameters
Parameter Type Req? Default Description
sessionId String No   Session ID
Request Empty
Response KnowledgeBaseMeta 

Get Federated Knowledge Base Document Categories

Category Complex Type

Field Type Description
id String unique category identifier
name String name of category
Description get list of categories
URL /kbs/categories
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
URL Parameters
Parameter Type Req? Default Description
lang String No "_default" Language
subTenantId String No Sub tenant identifier
sessionId String No Sessionn identifier
Request list of knowledge base identifiers
Response CategoryFaceItem
Notes If successful, 200 OK is sent back as response. If the dataset already exists, 400 BAD REQUEST is sent back

Get Knowledge Base Document Categories

Category Complex Type

Field Type Description
id String Category identifier
kbid String Knowledge Base identifier
name String Category name

Get Knowledge Base Document Categories

Description Returns a list of categories
URL /kbs/{kbId}/categories
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Req? Default Description
lang String No "_default" Language
sessionId String No   Session ID
Request Empty
Response
Parameter Type Description
categories Category List of categories for a given knowledge base

Get Knowledge Base Documents Associated With A Given Category

Description Returns all document previews for the specified category
URL /kbs/{kbId}/{catId}/documents
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
{catId} String Specific category ID. Use _all for retrieving all documents, independently of category. Specify particular category ID for retrieving documents from this category.
URL parameters
Parameter Type Required Default Description
from int No 0 Start position for pagination, default=0
size int No 0 Size of page for pagination, default=0. 0 means that you are about to retrieve all documents, related to given category.
lang String No "_default" Language ID
sessionId String No Session ID
Request Empty
Response
Field Type Description
count int Total count of documents in selection (pagination-independent)
page Pagination Pagination information
documents DocumentEntry Resulting selection of document
categories CategoryFacetItem Facet selection of categories, related to selected document set

Get Top X Trending Documents

Description Returns the top X trending documents
URL /kbs/{kbId}/top
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Required Default Description
lang String No "_default" Language
size Integer No   Size of selection to retrieve
sessionId String No   Session id
Request Empty
Response
Field Type Description
count int Total count of documents in selection (pagination-independent)
documents DocumentEntry Resulting selection in document
categories CategoryFacetItem Facet selection of categories, related to selected document set

Get Full Contents Of Document

DocumentContentEntry Complex Type

Field Type Description
All the fields of DocumentEntry
answerContentType String Content type for rich rendering content of answer from field answerContent
answerContent String May contain content of answer in rich markup format, for instance in form of “text/html”
attachments String [] List of urls of attachments that are related to this document.

Get full contents of the specified document

Description Returns the full content of the specified document
URL /kbs/{kbId}/documents/{docId}
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String Unique document ID
URL parameters
Parameter Type Required Default Description
lang String No "_default" Language ID
sessionId String No   Session ID
Request Empty
Response DocumentEntry
 

Retrieve favorites from a specified knowledge base

Description Retrieves list of favorite documents for particular knowledge base
URL /kbs/{kbId}/documents/favorites
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response

Retrieve list of all favorites

Description Retrieves list of all favorites from knowledge base
URL /kbs/documents/favorites
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response  

Retrieve list of suggested documents from a specified knowledge base

Description Retrieves a list of suggested documents for a particular knowledge base
URL /kbs/{kbId}/drafts
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response

Retrieve list of all documents from knowledge base

Description Retrieves list of all documents from knowledge base
URL /kbs/drafts
Method GET
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response

Add document to favorites

Description Adds a document to favorites
URL /kbs/{kbId}/documents/{docId}/favorites
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response  

Creating a suggested document

Description Creates a suggested document for the knowledge base
URL /kbs/{kbId}/drafts
Method POST
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response

Deleting a document from Favorites

Description Deletes a document from Favorites
URL /kbs/{kbId}/documents/{docId}/favorites
Method DELETE
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
{docId} String
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response

Processing the suggested document

Description Processes the suggested document
URL /kbs/{kbId}/drafts/{draftId}
Method DELETE
Request Content-Type
Response Content-Type application/json
Role Any
URL Identifiers
Parameter Type Description
{kbId} String Knowledge base ID
{draftId} String
URL parameters
Parameter Type Required Default Description
subTenantId String No Sub tenant identifier
lang String Yes Language ID
sessionId String No Session ID
Request Empty
Response
This page was last modified on March 11, 2016, at 16:04.

Feedback

Comment on this article:

blog comments powered by Disqus