Before beginning with these APIs, review the Getting Started article.

Overview

Here are the APIs at a glance:

API Description
Search Articles Retrieves the answers (article matches) to a given search phrase from a specific knowledge base.
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.
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.

Search Articles API

Retrieves the answers (article matches) to a given search phrase from a specific knowledge base.

Optionally, you can send the answers to an LLM (Large Language Model) service to be formulated into a single, enriched answer. The enriched answer is then returned in the response.

Learn how to get started with enriched answers via Generative AI. This involves activating the feature after reviewing and accepting terms and conditions.

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

Request

Headers
Header name Value Required
authorization Authorization token Yes
x-api-key API key Yes
Content-Type application/json 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
consumerQuery Search phrase String Yes
searchMode KAI_SEARCH for KnowledgeAI search, INTENTS_ONLY for Intent match only, or AI_SEARCH_ONLY for AI Search only. Learn about search methods. KAI_SEARCH,
INTENTS_ONLY,
AI_SEARCH_ONLY		 Yes
confidenceLevel The confidence threshold that matched answers must meet VERY_GOOD,
GOOD,
FAIR_PLUS,
FAIR,
POOR		 Yes
numberOfAnswers A value of 1, 2, 3, 4, or 5. This parameter determines two things: First, it determines how many matched articles to retrieve from the knowledge base and send to the LLM-powered service to generate a single, enriched answer. Second, it determines how many answers to include in the response from the API. Learn more below. Numeric Yes
fallbackTextMatch If true or unset, a text search is performed as a last-attempt search to find matching articles when earlier searches in the search flow don’t yield any results. This plain text search evaluates the input query against the titles and summaries in articles. If false, a last-attempt text match search isn’t performed.

The advantage to using this search is that it can return results when the earlier searches don’t. However, sometimes it can yield false positives, so you might want to turn it off.		 true, false No
channel The consumer channel where the answers are presented String (sample values: lp_web or web, lp_sms or sms, lp_whatsapp, lp_abc, inapp or lp_inapp, lp_fb, lp_viber, lp_line, lp_twitter, lp_voice). If unknown, use lp_web or web since this parameter is mandatory. Yes
llmConfig Learn about this Object immediately below. Object No

llmConfig Object

Name Description Type/Value Required
llmEnrichment If true, the LLM service is called to formulate a single, enriched answer via Generative AI. If false, the LLM service isn't called. Boolean (true or false) No
enrichmentPrompt When the consumer’s query is matched to articles in the knowledge bases, this is the prompt to send to the LLM service. The prompt instructs the LLM service on how to use the matched articles to generate an enriched answer.

When writing a prompt, you don't need to start from scratch. Check out the Prompt Library in Conversational Cloud. LivePerson provides prompt templates that you can quickly and easily copy.

Note: If llmEnrichment is true, but you don't specify an enrichment prompt, the default prompt for LivePerson Conversation Builder messaging bots is used.		 String (the prompt instructions) No
noArticleMatchPrompt When the consumer’s query isn’t matched to any articles in any knowledge bases, this is the prompt to send to the LLM service. The prompt instructs the LLM service on how to generate a response. If you don’t select a No Article Match prompt, if a matched article isn’t found, no call is made to the LLM service for a response. String (the prompt instructions) No
Setting numberOfAnswers

If you set numberOfAnswers to 1, only the top scoring article is used by the LLM service to generate the enriched answer, and only that enriched answer is returned in the response. The enriched answer is always considered the top answer match, i.e., the article at index 0.

If you set numberOfAnswers to a higher number, keep in mind that the setting has two purposes. If there's more than one article match, multiple articles will be used by the LLM service to generate the single, enriched answer (purpose 1). But this also means that the response includes multiple answers, i.e., the enriched answer plus some unenriched answers too (purpose 2).

It can be advantageous to specify a number higher than 1 because more knowledge coverage is provided to the LLM service when generating the enriched answer. As a result, the enriched answer is often better than when it's generated using just a single article. As mentioned above, the enriched answer is always considered the top answer match, i.e., the article at index 0.

Setting llmConfig

If you set llmEnrichment to true, the LLM service is called to formulate a single, enriched answer via Generative AI. For example, assume the knowledge base search retrieved four article matches of good quality. In order of confidence score, these are A1, A2, A3, and A4. After the LLM service does it work, the summary field for the highest scoring article (A1) contains the enriched answer, and A1’s summary before enrichment is moved to the answerBeforeEnrichment field, for that specific article only in the response.

Request body
{
"consumerQuery":"String",
"searchMode":"String",
"confidenceLevel": "String",
"numberOfAnswers": “String”,
"channel": "String",
"llmConfig": {
    “llmEnrichment”: “Boolean”,
    "enrichmentPrompt": "String",
    "noArticleMatchPrompt": "String"
    }
}

Response format

[
   {
       "articleId": "String",
       "tags": [
           "Tag 1",
           "Tag 2",
           "Tag 3"
       ],
       "title": "String",
       "summary": "String",
       "detail":"String",
       "knowledgeBaseId": "String",
       "llmUsed": "Boolean",
       "answerBeforeEnrichment":"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 Knowledge base data source was not found for the given ID
429 Too many requests
500 Internal server error

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

Articles return a status of "Active" or "Pending" (inactive). Learn about active and inactive articles.

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

Articles return a status of "Active" or "Pending" (inactive). Learn about active and inactive articles.

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 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
Query parameters
Parameter name Description Type Required
startTime The start time in epoch milliseconds String Yes
endTime The end time in epoch milliseconds String Yes

Response format

{
    "startTime": 1709229600000,
    "endTime": 1711616400000,
    "intervals": [
        {
            "kbClient": "CONV_ASSIST",
            "periodStartTime": 1710388800000,
            "numberOfQuestions": 11,
            "numberOfAnswers": 3,
            "numberOfAnsweredConversations": 2,
            "numberOfQueriedConversations": 3,
            "numberOfBotConversations": 3
        },
        {
            "kbClient": "CB",
            "periodStartTime": 1710430200000,
            "numberOfQuestions": 1,
            "numberOfAnswers": 1,
            "numberOfAnsweredConversations": 1,
            "numberOfQueriedConversations": 1,
            "numberOfBotConversations": 12
        },
...
...
...
]
}

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
startTime The start time in epoch milliseconds String Yes
endTime The end time in epoch milliseconds String Yes

Response format

{
    "startTime": 1709229600000,
    "endTime": 1711616400000,
    "intervals": [
        {
            "kbClient": "CONV_ASSIST",
            "periodStartTime": 1710388800000,
            "numberOfQuestions": 11,
            "numberOfAnswers": 3,
            "numberOfAnsweredConversations": 2,
            "numberOfQueriedConversations": 3,
            "numberOfBotConversations": 3
        },
        {
            "kbClient": "CB",
            "periodStartTime": 1710430200000,
            "numberOfQuestions": 1,
            "numberOfAnswers": 1,
            "numberOfAnsweredConversations": 1,
            "numberOfQueriedConversations": 1,
            "numberOfBotConversations": 12
        },
...
...
...
]
}

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