Jump to: navigation, search

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 CMS
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"
}
This page was last modified on March 11, 2016, at 16:04.

Feedback

Comment on this article:

blog comments powered by Disqus