KnowledgeAI — KnowledgeAI External APIs | LivePerson Developer Center

Overview

Here are the APIs at a glance:

API	Description
Get All Knowledge Bases	Retrieves the details for all knowledge bases for an account.
Get Knowledge Base by ID	Retrieves the details for a specific knowledge base.
Get All Articles in a Knowledge Base	Retrieves all articles in a knowledge base.
Get Article by ID	Retrieves a specific article.
Search Articles by Phrase	Retrieves the answers to a given search phrase from a specific knowledge base.
Get Metrics	Retrieves the knowledge base metrics for an account for a specific duration. Metrics include things like top served knowledge bases, top and least answered articles, top and least discovered intents, etc.
Get Metrics by Knowledge Base	Retrieves the metrics for a specific knowledge base for a specific duration. Metrics include things like top and least answered articles, top and least discovered intents, etc.
Get Usage Trend	Retrieves the usage trends for an account for a specific duration. Usage trends include things like the number of queried conversations, the number of answered conversations, etc.
Get Usage Trend by Knowledge Base	Retrieves the usage trends for a specific knowledge base for a specific duration. Usage trends include things like the number of queried conversations, the number of answered conversations, etc.

Get All Knowledge Bases API

Retrieves the details for all knowledge bases for an account.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account_id}/knowledgeBases
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Parameter	Description	Type	Required
account_id	Account ID	String	Yes

Response format

[
    {
        "knowledgeBaseId": "string",
        "name": "string",
        "type": "string",
        "status": "string",
        "url": "string",
        "langCode": "string",
        "intentAssociationType": "string",
        “domainId": "string",
        “domainName": "string",
        "createdTime": long,
        "modifiedTime": long,
        "createdBy": "String",
        "modifiedBy": "String",
        "createdByName": "String",
        "modifiedByName": "String",
        "domainType": "String"
    },
    {
        "knowledgeBaseId": "String",
        "name": "String",
        "type": "String",
        "status": "String",
        "url": "String",
        "langCode": "String",
        "entitiesAvailable": boolean,
        "intentAssociationType": "String",
        “domainId": "string",
        “domainName": "string",
        "createdTime": long,
        "modifiedTime": long,
        "createdBy": "String",
        "modifiedBy": "String",
        "createdByName": "String",
        "modifiedByName": "String",
        "domainType": "String",
     }
]

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get Knowledge Base by ID API

Retrieves the details for a specific knowledge base.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Parameter	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Response format

{
        "kbId": "String",
        "name": "String",
        "type": "String",
        "status": "String",
        "url": "String",
        "langCode": "String",
        "intentAssociationType": "String",
        "entitiesDataSourceId": "String",
        "publicKB": boolean,
        "createdTime": long,
        "modifiedTime": long,
        "createdBy": "String",
        "modifiedBy": "String",
        "createdByName": "String",
        "modifiedByName": "String",
        "domainType": "String",
        "kbMetrics": {
            "numOfArticles": Integer,
            "numOfActiveArticles": Integer,
            "numOfArticlesHaveIntents": Integer,
            "lastContentUpdatedTime": Long,
            "modifiedTime": Long,
            "createdTime": Long
        }
}

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get All Articles in a Knowledge Base API

Retrieves all articles in a knowledge base.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}/articles
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Parameter	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Response format

[  {
       "articleId": "String",
       "tags": [
           "Tag 1",
           "Tag 2",
           "Tag 3"
       ],
       "title": "String",
       "summary": "String",
       "detail":"String",
       "knowledgeBaseId": "String",
       “intentId”: “String”,
       “intentName”: “String”,
       "confidenceScore": 0.33,
       "confidenceLevel": "String",
       "category": "String",
       "createdTime": Long,
       "modifiedTime": Long,
       "status": "String",
       “imageUrl”:”String”,
       "audioUrl": "String",
       "contentUrl": "String",
       "videoUrl": "String",
   }
]

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get Article by ID API

Retrieves a specific article.

Description	Value
Apigee proxy path	cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}/articles/{article-id}
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Parameter	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes
article_id	Article ID	String	Yes

Response format

{
       "articleId": "String",
       "tags": [
           "Tag 1",
           "Tag 2",
           "Tag 3"
       ],
       "title": "String",
       "summary": "String",
       "detail":"String",
       "knowledgeBaseId": "String",
       “intentId”: “String”,
       “intentName”: “String”,,
       "category": "String",
       "createdTime": Long,
       "modifiedTime": Long,
       "status": "String",
       “imageUrl”:”String”,
       "audioUrl": "String",
       "contentUrl": "String",
       "videoUrl": "String",
   }

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Search Articles by Phrase API

Retrieves the answers to a given search phrase from a specific knowledge base.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}/articles/search
HTTP method	POST

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Parameter	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Body/POST parameters

Name	Description	Type/Value	Required	Note
searchPhrase	Search phrase	String	Yes
searchMode	intents for KnowledgeAI, intents_only for Intent match only, all for AI search only	intents, intents_only, all	Yes	In a future release, we’ll deprecate these values and replace them with new constants. However, these values will still work for backwards compatibility.
numOfResults	Value between 1 to 5	Numeric	Yes
knowledgeBaseId	Knowledge base ID	String	Yes
confidenceThreshold	vg for very good, g for good, fp for fair plus	vg, g, fp	Yes

Request body

{
"searchPhrase":"String",
"searchMode":"String",
"numOfResults":String,
"knowledgeBaseId": "String",
"confidenceThreshold":"String"
}

Response format

[
   {
       "articleId": "String",
       "tags": [
           "Tag 1",
           "Tag 2",
           "Tag 3"
       ],
       "title": "String",
       "summary": "String",
       "detail":"String",
       "knowledgeBaseId": "String",
       “intentId”: “String”,
       “intentName”: “String”,
       "confidenceScore": Double,
       "confidenceLevel": "String",
       "category": "String",
       "createdTime": Long,
       "modifiedTime": Long,
       "status": "ACTIVE",
       “imageUrl”:”String”,
       "audioUrl": "string",
       "contentUrl": "string",
       "videoUrl": "string",
   }
]

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response; search parameters did not yield any results
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID
429	Too many
500	Internal server error

Get Metrics API

Retrieves the knowledge base metrics for an account for a specific duration.

Metrics include things like top served knowledge bases, top and least answered articles, top and least discovered intents, etc.

Description	Value
Apigee proxy path	cb/kai/v1/accounts/{account-id}/metrics
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Field name	Description	Type	Required
account_id	Account ID	String	Yes

Query parameters

Parameter name	Description	Type	Required	Notes
duration	Duration of metrics	String	Yes	Valid values: SEVEN_DAYS THIRTY_DAYS NINETY_DAYS

Response format

{
   "organizationId": "String",
   "duration": "String",
   "numberOfQuestions": String,
   "numberOfAnswers": String,
   "topAnsweredArticles": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "knowledgeBaseId": "String",
           "knowledgeBaseName": "String",
           "count": String,
           "intentMatchPercentage": String
       }
   ],
   "leastAnsweredArticles": [
       {
           "articleId": "String,
           "articleTitle": "String",
           "knowledgeBaseId": "String",
           "knowledgeBaseName": "String",
           "count": String,
           "intentMatchPercentage": String
       }
   ],
   "topDiscoveredIntents": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "intentId": "String",
           "intentName": "String",
           "domainId": "String",
           "domainName": "String",
           "count": String
       }
   ],
   "leastDiscoveredIntents": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "intentId": "String",
           "intentName": "String",
           "domainId": "String",
           "domainName": "String",
           "count": String
       }
   ],
   "topServedKnowledgeBases": [
       {
           "knowledgeBaseId": "String,
           "knowledgeBaseName": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String
       }
   ]
}

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get Metrics by Knowledge Base API

Retrieves the metrics for a specific knowledge base for a specific duration.

Metrics include things like top and least answered articles, top and least discovered intents, etc.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}/metrics
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Field name	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Query parameters

Parameter name	Description	Type	Required	Notes
duration	Duration of metrics	String	Yes	Valid values: SEVEN_DAYS, THIRTY_DAYS, NINETY_DAYS

Response format

{
   "organizationId": "String",
   "duration": "String",
   "numberOfQuestions": String,
   "numberOfAnswers": String,
   "topAnsweredArticles": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "knowledgeBaseId": "String",
           "knowledgeBaseName": "String",
           "count": String,
           "intentMatchPercentage": String
       }
   ],
   "leastAnsweredArticles": [
       {
           "articleId": "String,
           "articleTitle": "String",
           "knowledgeBaseId": "String",
           "knowledgeBaseName": "String",
           "count": String,
           "intentMatchPercentage": String
       }
   ],
   "topDiscoveredIntents": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "intentId": "String",
           "intentName": "String",
           "domainId": "String",
           "domainName": "String",
           "count": String
       }
   ],
   "leastDiscoveredIntents": [
       {
           "articleId": "String",
           "articleTitle": "String",
           "intentId": "String",
           "intentName": "String",
           "domainId": "String",
           "domainName": "String",
           "count": String
       }
   ],
   "topServedKnowledgeBases": [
       {
           "knowledgeBaseId": "String,
           "knowledgeBaseName": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String
       }
   ]
}

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get Usage Trend API

Retrieves the usage trends for an account for a specific duration.

Usage trends include things like the number of queried conversations, the number of answered conversations, etc.

Description	Value
Apigee proxy path	cb/kai/v1/accounts/{account-id}/metrics/trend
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Field name	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Query parameters

Parameter name	Description	Type	Required	Notes
duration	Duration of metrics	String	Yes	Valid values: SEVEN_DAYS, THIRTY_DAYS, NINETY_DAYS

Response format

{
   "duration": "String",
   "count": {
       "CONV_ASSIST": {
           "kbClient": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       },
       "CB": {
           "kbClient": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       }
   },
   "events": [
       {
           "kbClient": "String",
           "periodStartTime": long,
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       }   ]
}

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error

Get Usage Trend by Knowledge Base API

Retrieves the usage trends for a specific knowledge base for a specific duration.

Usage trends include things like the number of queried conversations, the number of answered conversations, etc.

Description	Value
Apigee proxy path	/cb/kai/v1/accounts/{account-id}/knowledgeBases/{kb-id}/metrics/trend
HTTP method	GET

Request

Headers

Header name	Value	Required
authorization	Authorization token	Yes
x-api-key	API key	Yes
channel-name	Channel name	Yes

Path parameters

Field name	Description	Type	Required
account_id	Account ID	String	Yes
kb_id	Knowledge base ID	String	Yes

Query parameters

Parameter name	Description	Type	Required	Notes
duration	Duration of metrics	String	Yes	Valid values: SEVEN_DAYS, THIRTY_DAYS, NINETY_DAYS

Response format

{
   "duration": "String",
   "count": {
       "CONV_ASSIST": {
           "kbClient": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       },
       "CB": {
           "kbClient": "String",
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       }
   },
   "events": [
       {
           "kbClient": "String",
           "periodStartTime": Long,
           "numberOfQuestions": String,
           "numberOfAnswers": String,
           "numberOfAnsweredConversations": String,
           "numberOfQueriedConversations": String,
           "numberOfBotConversations": String
       }
        ]
}

Response status

There’s no response body for non-200 status codes.

Status code	Description
200	Success response
400	Bad request; request validation failures
401	Not authorized to access the resource
404	Requested response was not found; knowledge base data source was not found for the given ID; search parameters did not yield any results
429	Too many requests
500	Internal server error