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