Management API

Management REST API Overview

This API enables external systems to manage the content of knowledge bases stored in the index of Genesys Knowledge Server.

Authorization

You must have author privileges to access the Management API. This can be configured in the Knowledge Center Administrator plugin.

Overview of Management API Requests

Method	URL	Description
POST	/management/kbs/{kbId}/langs/{lang}/docs	Create or update Knowledge documents for a specific language in a specific knowledge base
DELETE	/management/kbs/{kbId}/langs/{lang}/docs	Remove knowledge documents for a specific language in a specific knowledge base
GET	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative	For the specified knowledge document, get a set of alternative questions for a specific language in a specific knowledge base
POST	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative	For the specified knowledge document, add a set of alternative questions for a specific language in a specific knowledge base
DELETE	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative	Remove the specified alternative questions from a knowledge document for a specific language in a specific knowledge base
GET	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/feedbacks	Gather feedback on the specified knowledge document for a specific language in a specific knowledge base
GET	/management/kbs/{kbId}/langs/{lang}/reports/unanswered	Gather unanswered questions for a specific language in a specific knowledge base
DELETE	/management/kbs/{kbId}/langs/{lang}/reports/unanswered	Mark unanswered questions as processed for a specific language in a specific knowledge base
DELETE	/management/kbs/{kbId}/purge	Purge the specified knowledge base
DELETE	/management/kbs/purgeAll	Purge an entire knowledge space
Attachments
GET	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment	Return all attachments related to the specified document
POST	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment	Add a new attachment info to the specified document
POST	/management/kbs/{kbId}/langs/{langId}/docs/{docId}/attachments	Replaces all attachments and content of each attachment for given document
DELETE	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment	Remove an attachment from the specified document

Detailed Description of Management API Requests

Create Or Update Knowledge Documents

Description	Create or update knowledge documents for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Default Description {kbId} String Yes   Knowledge base ID {lang} String Yes   Language ID isComplete Boolean No False Is the content that was sent for the current knowledge base in the current language complete? If yes, then Knowledge Center Server completely recreates the current knowledge base tenantId String Yes Tenant identifier returnCreatedDocuments Boolean No True Does the response contain all of the content for each document that was created or updated, or just their identifiers
Request Body	Field Type Required Description documents Collection<KnowledgeDocumentEntry> Yes Collection of Knowledge documents. If id of some Knowledge documents in the request body aren't specified or don't exist in the index of Knowledge server, then new Knowledge documents will be created in the index.
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR}. error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response IndexDocumentsStatus Yes
Notes	This request allows you to create new knowledge base+language branches in Knowledge Center Server. To create a new knowledge base with a new language, a knowledge document with the IDs of that knowledge base and language should be sent in the request body.

Index Document Status

Field	Type	Description
created	int	Number of documents that were added to index
updated	int	Number of updated documents
skipped	int	Number of documents that were not created or updated due to issues that occurred during the creation or update process. Extra information about each issue is placed into an indexStatus item, which has a DocumentStatus structure
indexStatus	DocumentStatus[] or ShortDocumentStatus[]	Status of processed (newly-created, updated, or skipped) knowledge documents. If returnCreatedDocuments == true then indexStatus has a type of DocumentStatus[]. Otherwise indexStatus has a type of ShortDocumentStatus[].

Remove Knowledge Documents

Description	Remove knowledge documents for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs
Method	DELETE
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID tenantId String Yes Tenant identifier
Request Body	Field Type Required Description documentIds Collection<String> Yes IDs of knowledge documents to be removed
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response DeleteDocumentsStatus No Status of the deleted documents

Delete Document Status

Field	Type	Description
deleted	int	Number of documents that were deleted from index
notfound	int	Number of documents that were not found
skipped	int	Number of documents that were not deleted due to issues that occurred during the deletion process. Extra information about each issue is placed into an indexStatus item, which has a DocumentStatus structure
indexStatus	ShortDocumentStatus[]	Status of processed (deleted, not found, or skipped) knowledge documents.

Get Alternative Questions

Description	For the specified knowledge document, get a set of alternative questions for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative
Method	GET
Request Content-Type	—
Response Content-Type	application/json
Role	CMS
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	—
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response Collection<String> No List of alternative texts for the document

Modify List of Alternative Questions in a Knowledge Document

Description	For the specified knowledge document, add a set of alternative questions for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	AGENT
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	Field Type Required Description alternativeQuestions Collection<String> Yes List of alternative questions to add to the knowledge document
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK).

Remove A List of Alternative Questions

Description	Remove the specified alternative questions from a knowledge document for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative
Method	DELETE
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	Field Type Required Description alternativeQuestions Collection<String> Yes List of alternative questions to remove from the knowledge document
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK).

Gather Feedback on a Knowledge Document

Description	Gather feedback on the specified knowledge document for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/feedbacks
Method	GET
Request Content-Type	application/json
Response Content-Type	application/json
Role	AGENT
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Use _all for retrieving all feedback, independently of document. Specify particular document ID for retrieving feedback for particular document. tenantId String Yes Tenant identifier from int No Pagination offset size int No Pagination page size, default 10 startDate Date No Start date of requested period endDate Date No End date of requested period duration String No Period with a duration of {{"now" – duration} – "now"} type String No "LIKE" or "DISLIKE" unprocessedOnly Boolean No "true" for retrieving feedback that wasn't marked as being processed by an agent, "false" for retrieving all feedback
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response FeedbackInfo No FeedbackInfo { count Long // total count of feedback items according to given parameters from Integer // pagination offset items Feedback[] // feedback items itselff size Integer // count of items in current page (pagination) } Feedback { id String // feedback item id document PartialDocument // stored in the feedback item essential document data moment String // when this event was registered into history originator String // "AGENT" | "CUSTOMER" question String // text of question type String // "POSITIVE" | "NEGATIVE" }

Gather Unanswered Questions

Description	Gather unanswered questions for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/reports/unanswered
Method	GET
Request Content-Type	application/json
Response Content-Type	application/json
Role	AGENT
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {kbId} String Yes Knowledge base ID {lang} String Yes Language ID tenantId String Yes Tenant identifier from int No Pagination offset size int No Pagination page size, default 10 startDate Date No Start date of requested period endDate Date No End date of requested period duration String No Period with a duration of {{"now" – duration} – "now"}
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response UnansweredInfo No UnansweredInfo { count Long // total count of feedback items according to given parameters from Integer // pagination offset items HistoryEntry[] // saved items of history size Integer // count of items in current page (pagination) } HistoryEntry { id String // history item id agentId String customerId String duration Integer // time of api call processing (milliseconds) knowledgebaseId String language String moment String // the moment of adding this history item (when it occured) nodename String // Knowledge Center node name originator String // AGENT, CUSTOMER processed String // flag of processing this event by agent sessionId String // session id tenantId String visitId String }

Mark Unanswered Questions As Processed

Description	Mark unanswered questions as processed for a specific language in a specific knowledge base
URL	/management/kbs/{kbId}/langs/{lang}/reports/unanswered
Method	DELETE
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID tenantId String Yes Tenant identifier
Request Body	Field Type Required Description historyIds Collection<String> Yes IDs of history items to mark as processed
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK).

Purge a Specific Knowledge Base

Description	Purge the specified knowledge base
URL	/management/kbs/{kbId}/purge
Method	DELETE
Request Content-Type	—
Response Content-Type	application/json
Role	ADMINISTRATOR
Parameters	Parameter Type Required Description {kbId} String Yes ID of knowledge base to be purged tenantId String Yes Tenant identifier
Request Body	—
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK).

Purge An Entire Knowledge Space

Description	Purge an entire knowledge space
URL	/management/kbs/purgeAll
Method	DELETE
Request Content-Type	—
Response Content-Type	application/json
Role	ADMINISTRATOR
Parameters	Parameter Type Required Description {kbId} String Yes ID of knowledge base to be purged tenantId String Yes Tenant identifier
Request Body	—
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK).

Get All Attachments

Description	Return all attachments related to the specified document
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment
Method	GET
Request Content-Type	—
Response Content-Type	application/json
Role	AGENT
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	—
Response Body	Field Type Required Description statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR} error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response Attachment No List of attachments: See Attachment global type described below

Add Attachment

Description	Add a new attachment into the specified document
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	Field Type Description fileName String Original file name url String URL of the file content String Base64-encoded document content Warning The knowledge server indexes the starting 32K of the extracted text content.
Response Body	Field Type Required Description error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response IndexDocumentsStatus Yes   statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR}
Notes	Note that the attachment URL serves as a primary key for the attachment. In the context of a particular document, all URLs must be unique. See all supported document formats on the Apache Tika page

Replace Attachments

Description	Replaces all attachments and content of each attachment, for a given document
URL	/management/kbs/{kbId}/langs/{langId}/docs/{docId}/attachments
Method	POST
Request Content-Type	application/json
Response Content-Type	application/json
Role	Author
URL Parameters	Parameter Type Required Description {kbId} String Yes id of knowledge base {langId} String Yes language Id {docId} String Yes document Id tenantId String Yes Tenant identifier
URL Identifiers	—
Request	Field Type Description attachments Attachment [] List of related to document attachments including content of each attachment The structure of Attachment is: Field Type Description fileName String Original file name url String URL to the file content String Base64-encoded document content Warning The knowledge server indexes the starting 32K of the extracted text content.
Response	Field Type Required Description error Error Yes (if statusCode <> 200) Detailed information of the error message. Present only if operation execution was unsuccessful (statusCode <> 200) response IndexDocumentsStatus Yes — statusCode int Yes —
Notes	The attachment url serves as a primary key for the attachment. In the context of a particular document, all URLs mast be unique. See all supported document formats on Apache Tika page.

Remove Attachments

Description	Remove a list of attachments from the specified document
URL	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/attachment
Method	DELETE
Request Content-Type	application/json
Response Content-Type	application/json
Role	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID tenantId String Yes Tenant identifier
Request Body	Field Type Description url String[] The list of URLs of attachments to remove from the document
Response Body	Field Type Required Description error Error Yes (if statusCode <> OK) Detailed information about the error message. Present only if the operation executed unsuccessfully (statusCode <> OK). response IndexDocumentsStatus Yes   statusCode RestStatus Yes Execution code of the operation—duplicates HTTP code. Enum of {OK, NOT_FOUND, BAD_REQUEST, UNAUTHORIZED, METHOD_NOT_ALLOWED, INTERNAL_SERVER_ERROR}

Complex Types—Requests

KnowledgeDocumentEntry

API - oriented Knowledge Document representation

Field	Type	Description
id	String	unique document identifier
url	String	external url, related to this particular document
media	String[]	list of media types, associated with this document
tags	String[]	list of tags, related to document
categories	Category[]	list of id of categories, associated with particular document
customFields	Map<String, Object>	set of custom fields values
Fields of document of QNA knowledge type only
question	String	QNA question
answer	String	QNA answer
Fields of document of ARTICLE knowledge type only
title	Sting	Article title
description	String	Article description
summary	String	Article summary

Category

Field	Type	Required	Description
id	String	No	Category ID
name	String	Yes	Category name

Custom Field

Field	Type	Required	Description
name	String	Yes	Custom field name
value	String	Yes	Custom field value

Feedback

Field	Type	Required	Description
type	String	Yes	Type of feedback: "POSITIVE" or "NEGATIVE"
originator	String	Yes	Role of the person who originated the feedback: "AGENT" or "CUSTOMER"
moment	Date	Yes	The moment when the feedback was registered
question	String	Yes	Question posted by the originator

Complex Types—Responses

Document Status

Field	Type	Required	Description
operationStatus	String	Yes	Status of executed operation: "ADDED", "UPDATED", "DELETED", "ERROR"
document	KnowledgeDocumentEntry	No	ID of resultant knowledge document
errorMessage	String	No	Provided if operationStatus == "ERROR"

ShortDocumentStatus

Field	Type	Required	Description
operationStatus	String	Yes	Status of executed operation: "ADDED", "UPDATED", "DELETED", "ERROR", "NOTFOUND"
document	String	No	ID of resultant FAQ document
errorMessage	String	No	Provided if operationStatus == "ERROR"

RestStatus Global Enum

The RestStatus enum provides a status code with the following values:

RestStatus : {

CONTINUE, SWITCHING_PROTOCOLS, OK, CREATED, ACCEPTED, NON_AUTHORITATIVE_INFORMATION, NO_CONTENT, RESET_CONTENT, PARTIAL_CONTENT, MULTI_STATUS, MULTIPLE_CHOICES, MOVED_PERMANENTLY, FOUND, SEE_OTHER, NOT_MODIFIED, USE_PROXY, TEMPORARY_REDIRECT, BAD_REQUEST, UNAUTHORIZED, PAYMENT_REQUIRED, FORBIDDEN, NOT_FOUND, METHOD_NOT_ALLOWED, NOT_ACCEPTABLE, PROXY_AUTHENTICATION, REQUEST_TIMEOUT, CONFLICT, GONE, LENGTH_REQUIRED, PRECONDITION_FAILED, REQUEST_ENTITY_TOO_LARGE, REQUEST_URI_TOO_LONG, UNSUPPORTED_MEDIA_TYPE, REQUESTED_RANGE_NOT_SATISFIED, EXPECTATION_FAILED, UNPROCESSABLE_ENTITY, LOCKED, FAILED_DEPENDENCY, INTERNAL_SERVER_ERROR, NOT_IMPLEMENTED, BAD_GATEWAY, SERVICE_UNAVAILABLE, GATEWAY_TIMEOUT, HTTP_VERSION_NOT_SUPPORTED, INSUFFICIENT_STORAGE

}

Attachment Global Type

Attachment {
  file_name : String, // name of attached file
  url : String,       // url for obtaining attachment content
  modified : String   // date of last modification of attachment
 in format of "yyyy-MM-dd HH:mm:ss"
}