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

DocumentEntry complex type

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

Feedback

Comment on this article:

blog comments powered by Disqus
This page was last modified on May 29, 2018, at 12:38.