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 FAQ documents for a specific language in a specific knowledge base
DELETE	/management/kbs/{kbId}/langs/{lang}/docs	Remove FAQ documents for a specific language in a specific knowledge base
GET	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/alternative	For the specified FAQ 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 FAQ 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 FAQ document for a specific language in a specific knowledge base
GET	/management/kbs/{kbId}/langs/{lang}/docs/{docId}/feedbacks	Gather feedback on the specified FAQ 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
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 FAQ Documents

Description	Create or update FAQ 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 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 (FAQ) Yes Collection of FAQ documents. If the IDs of some of the FAQ documents in the request body aren't specified or don't exist in the index of Knowledge Center Server, then new FAQ 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 FAQ 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) FAQ documents. If returnCreatedDocuments == true then indexStatus has a type of DocumentStatus[]. Otherwise indexStatus has a type of ShortDocumentStatus[].

Remove FAQ Documents

Description	Remove FAQ 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
Request Body	Field Type Required Description documentIds Collection<String> Yes IDs of FAQ 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) FAQ documents.

Get Alternative Questions

Description	For the specified FAQ 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	AUTHOR
Parameters	Parameter Type Required Description {kbId} String Yes Knowledge base ID {lang} String Yes Language ID {docId} String Yes Document ID
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 FAQs for the document

Modify List of Alternative Questions in a FAQ Document

Description	For the specified FAQ 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
Request Body	Field Type Required Description alternativeQuestions Collection<String> Yes List of alternative questions to add to the FAQ 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 FAQ 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
Request Body	Field Type Required Description alternativeQuestions Collection<String> Yes List of alternative questions to remove from the FAQ 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 FAQ Document

Description	Gather feedback on the specified FAQ 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. 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 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
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
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
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
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 info to 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
Request Body	Field Type Description fileName String Original file name url String URL of the file content String Base64-encoded document 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

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

FAQ

Field	Type	Required	Description
id	String	Optional	If it isn't specified in the request body, a new FAQ document ID will be generated
question	String	Mandatory	Text of the question
answer	String	Mandatory	Text of the answer
categories	Collection<Category>	Optional	List of the categories a FAQ document belongs to
customFields	Map<String : String>	Optional	List Custom fields in document
media	String []	Optional	Media type of a FAQ document
tags	String []	Optional	Related tags
url	String	Optional	Related outer URL
created	String	no effect in request (skip it in requests)	Date of document creation
modified	String	no effect in request (skip it in requests)	Date of last modification of document
kbId	String	no effect in request (skip it in requests)	Knowledge base where a document belongs
language	String	no effect in request (skip it in requests)	Language of document

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	FAQ	No	ID of resultant FAQ 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"
}