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