For release 8.6 and later, this content is moved to the Pega Knowledge Implementation Guide.

Pega Knowledge provides the following REST APIs to help expose knowledge articles, taxonomy categories, and search capabilities in your web applications:

• articles/KMCreateArticle
• articles/KMGetArticleByID/{ArticleId}
• articles/KMListArticlesByTaxonomy/{TaxKey}
• articles/KMRateArticle
• search/KMGetArticlesAndPosts
• articles/KMCreateArticleSuggestion
• downloads/KMDownloadAttachments/{AttachmentKey}
• discussions/KMGetCommunityPostByID
• discussions/KMGetCommunityPostsByCategory
• discussions/KMGetUserCommunityPost

Accessing the PegaKMREST service package

The Pega Knowledge REST APIs are included in the PegaKMREST service package. To access the PegaKMREST service package:

1. In the navigation pane of Dev Studio, click Records > Integration-Resources > Service Package.
2. In the list of service packages, search for, or locate PegaKMREST.
3. Click PegaKMREST to open the service package and display the list of APIs, endpoint URLs, and other related information.

Using the Pega Knowledge APIs

Perform the following steps to use the Pega Knowledge REST APIs:

1. In the navigation pane of Dev Studio, click Records > Security > OAuth 2.0 Client Registration, and then open the KMOAuthClient rule. 

2. Generate the client secret, and then record the client ID and the client secret.
3. Add the KMServiceUserAG and KMServiceUser rules to your implementation ruleset.

For information on testing a REST API, see Using OAuth2 authentication with the Pega-provided Swagger UI.

articles/KMCreateArticle

Creates an article using the data provided. The system routes the draft article to the New drafts workbasket and processes it through the normal publication workflow. This API allows up to five file attachments with each article, with a maximum file attachment size of 5MB. Limiting the file attachment size helps to control the size of the database and the performance of the application, the search index, general searching, and the response time for users who are accessing file attachments in the user interface or portal. The API also supports the standard file attachment types (.docx, .xlsx, .pptx, and .pdf) and image attachment types (.jpg, .gif, .png, and .svg) that Pega platform supports.

Restricted file types

The following file types are restricted from use in the API import process. You can also add additional file types that you want to restrict from the import process. The ability to restrict additional file types provides flexibility and increased security based on your business needs and security standards. If the application encounters any of the restricted file types, it generates an error code and a corresponding error message.

• .exe
• .com
• .bat
• .cmd
• .msi

• .vb or .vbs

• .scf
• .scr
• .pif
• .zip
• .rar

To add additional file types to the restricted list:

1. Log in to the Pega Knowledge authoring portal.
2. On the left pane, click Configuration, and then select Article API configuration.
3. In the Restricted file type field, enter the file type you want to restrict, and then click Add.
4. Click Save.

Method: POST

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMCreateArticle

Request Header

The Request header should contain Content-Type as a multipart/form-data and boundary that you define with the other data.

Example:  Content-Type: multipart/form-data; boundary=--------abc123

Query parameters

* Mandatory parameters

Request body

If the content type is set to "Authored", the Request body should contain text for the article body. Because the system sends the request as multipart/form-data, the request body can contain data in the key value format, as shown in the following example:

Example:Content-Disposition: form-data; name=”Body”

Request parameters

Sample request body

The following sample request body contains text for the article body along with an image file in key value format.

File: 0.jpg
Body: this is text for article body
The Http code for the above request body will be as---------------------------------360742209208194055953283
Content-Disposition: form-data; name="file"; filename="0.jpg"
<0.jpg>
--------------------------------------------36-742209208194055953283
Content-Disposition: form-data; name="Body"
this is text for article body

In the above sample code, ----------------------------360742209208194055953283 acts as boundary. File is the key and “0.jpg” is the value. Body is the key and "this is text for article body" is the value.

POST /prweb/PRRRestService/PegaKMREST/articles/KMCreateArticle?
ArticleTitle=This%20is%20rest%20API%20Demo&ArticleAbstract=This%20is%
20rest%20API%20Demo&ContentType=Authored&CategoryIDs=TAX-
1&ContentURL=&IsInternalContent=false&Tags=api&AticleLanguage=en

HTTP/1.1Authorization: Bearer
e3YxfWE3NTNjZTQ0NGM3ODEzMTg2NmFiOTNkNmE3MGE4NTc=

User-Agent: PostmanRuntime/7.26.3Accept: */*Cache-Control: no-
cachePostman-Token: 16347ab3-1e9c-4d1d-aef7-1b654c2fc456Host:
lab5203.lab.pega.comAccept-Encodng: gzip, deflate, brConnection: keep-alive

Content-Type: multipart/form-data; boundary=------------------------------
-544197066538882863805869

Content-Length: 38817 -----------------------54197066538882863805869

Content-Disposition: form-data; name="file";filename="0.jpg"

<0.jpg>
------------------------544197066538882863805869
Content-Disposition: form-data; name="Body"

this is text for article body
----------------------544197066538882863805869

Sample request

{ 
"ArticleAbstract":"",  "ArticleTitle":"",  "CategoryIds":"",  "ContentSourceAuthored":"",  "ContentSourceURL":"",  "ContentType":"",  "KMArticleLanguage":"",  "KMContentCreationSource":"",  "tagsList":""}

Sample response

{
  "ArticleAbstract":"This is a rest API Demo",  "ArticleTitle":"This is a rest API Demo",  "CategoryIds":"TAX-1",  "ContentSourceAuthored":"this is text for article body",  "ContentSourceURL":"",  "ContentType":"Authored",  "KMArticleLanguage":"en",  "KMContentCreationSource":"API",
  "pyID": "KC-7006",  "tagsList":"api"}

Configuring rate limits to mitigate Denial of Service attachments

You can set the number of articles that can be created via the API for a specific amount of time by configuring the Allowed articles volume and the Time (in minutes) to determine rate limit settings. Note that the combination of the values of these two fields determines the threshold for the rate limit. For example, if you select 1 for time and 1000 for article volume the system will process 1000 article creation requests per minute. If the system receives more than 1000 requests, it generates the following error message: "Rejecting request as number of requests exceeded threshold".

To configure the rate limit:

1. Log in to the Pega Knowledge authoring portal.
2. In the left pane, click Configuration, and then select Article API Configuration.
3. In the Time (in minutes) to determine rate limit field, select the time (in minutes).
4. In the Allowed articles volume field, select the number of articles that the system can create in the time specified.
5. Click Save.

Request validation errors

The API request must fulfill certain conditions to avoid errors. The sytem writes any errors to the response message. The following table lists the error conditions and corresponding error messages.

Attachment validation errors

If there are errors related to attachments, the system creates an article, but the response body will contain the attachment errors along with other details. If more than five attachments are received, only the first five attachments will be attached to the article. You must manually attach the remaining attachments to the article. The following table shows the error conditions and corresponding error messages for file attachments:

Configuring the virus scan stub

When you configure the CallVirusCheck utility stub, the system calls the utility before uploading any files. If the utility finds a virus, it will not save the file to the database. The system calls the utility for every attachment that is sent using REST API or that is uploaded manually. To handle any viruses that the utility finds, set the VirusCheckStatus parameter in the CallVirusCheck utility with the prefix “Virus”+Message.

articles/KMGetArticleByID/{ArticleId}

Gets the corresponding article data for the specified article ID.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMGetArticleByID/{ArticleId}

Path parameters

Response

{  "ArticleAbstract": "",  "ArticleTitle": "",  "Content": "",  "ContentType": "",  "URL": "",  "attachments": [    {      "AttachmentsType": "File",      "DownloadLink": "",      "FileAttachments": ""    }  ],  "tags": [    {      "TagName": ""    }  ],  "taxonomies": [    {      "ParentTaxonomyId": "",      "TaxonomyId": "",      "TaxonomyKey": "",      "TaxonomyName": "",      "TaxonomyPath": ""    }  ],  "referencedArticles": [       {         "ArticleID": "",         "ArticleTitle":""       }
  ]}

Sample response

{  "ArticleAbstract": "Risk is only one part of the equation when it comes to the impact of the GDPR. The other important “R” to watch – is its upcoming impact to your Revenue. Learn the key considerations that can allow your business to close both risk and revenue gaps, at the very same time.",  "ArticleTitle": "GDPR: Risk, Revenue, and Reward",  "Content": "<p>T<span style=\"font-family:OpenSans,sans-serif;\">he attached whitepaper explains the risks and opportunities associated with the new European Union General Data Protection Regulations (GDPR) and related regulations.</span></p>\r\n\r\n<p><span style=\"font-family:OpenSans,sans-serif;\">You can also click&nbsp;<a href=\"https://www1.pega.com/system/files/resources/2018-01/GDPR%20Risk%20Revenu%20wp-final-180130.pdf\" onclick=\"window.open(this.href, 'GDPR-Risk,Revenue,andReward', 'resizable=no,status=no,location=no,toolbar=no,menubar=no,fullscreen=no,scrollbars=no,dependent=no'); return false;\" title=\"GDPR - Risk, Revenue, and Reward\">here</a>&nbsp;to access the whitepaper.</span></p>",  "ContentType": "Authored",  "URL": "http://",  "attachments": [    {      "AttachmentsType": "File",      "DownloadLink": "https://10.60.215.52:8443/prweb/PRRestService/PegaKMREST/downloads/KMDownloadAttachments/DATA-WORKATTACH-FILE PEGAFW-KM-WORK KC-79!20180822T121731.854 GMT",      "FileAttachments": "GDPRRiskRevenuewpfinal.pdf"    }  ],  "tags": [
    {      "TagName": "gdpr"    },    {      "TagName": "data privacy"    },    {      "TagName": "privacy"    }  ],  "taxonomies": [    {      "ParentTaxonomyId": "TOP",      "TaxonomyId": "TAX-2",      "TaxonomyKey": "PEGAFW-KM-DATA-TAXONOMY TAX-2",      "TaxonomyName": "Customer Service",      "TaxonomyPath": "Customer Service"    }  ]}

articles/KMListArticlesByTaxonomy/{TaxKey}

Gets all the articles associated with a specified category ID.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMListArticlesByTaxonomy/{TaxKey}

Path parameters

Response

[
  {
    "pyStatusWork": "",
    "CurrentRating": 0,
    "ContentType": "",
    "pxPages": {
      "LC": {
        "TaxonomyKey": "",
        "pxSubscript": "LC"
      }
    },
    "pxCoverInsKey": "",
    "ArticleTitle": "",
    "pzInsKey": "",
    "AggregateRating": 0,
    "ContentSourceURL": "http://",
    "pyID": "",
    "pxCreateDateTime": "",
    "RatingsCount": 0,
    "pyLabel": "",
    "mixedValueType": "",
    "pxCreateOpName": "",
    "ArticleAbstract": "",
    "KMArticleLanguage": "",
    "LikePercentage": null,
    "KMDiagnosticsId": "",
    "ArticleViews": 0
  }
]

Sample Response

[  {    "pyStatusWork": "Resolved-Published",    "CurrentRating": 0,    "ContentType": "Authored",    "pxPages": {      "LC": {        "TaxonomyKey": "PEGAFW-KM-DATA-TAXONOMY TAX-2",        "pxSubscript": "LC"      }    },
    "pxCoverInsKey": "PEGAFW-KM-WORK KC-2",    "ArticleTitle": "5 Tips for handling difficult customers",    "pzInsKey": "PEGAFW-KM-WORK KCP-164",    "AggregateRating": 0,    "ContentSourceURL": "http://",    "pyID": "KCP-164",    "pxCreateDateTime": "20190625T151730.147 GMT",    "RatingsCount": 0,    "pyLabel": "5 Tips for handling difficult customers",    "mixedValueType": "",    "pxCreateOpName": "KM Admin",    "ArticleAbstract": "This article describes how to work with tough customers",    "KMArticleLanguage": "en",    "LikePercentage": null,    "KMDiagnosticsId": "",    "ArticleViews": 0  },  {    "pyStatusWork": "Resolved-Published",    "CurrentRating": 0,    "ContentType": "Authored",    "pxPages": {      "LC": {        "TaxonomyKey": "PEGAFW-KM-DATA-TAXONOMY TAX-2",        "pxSubscript": "LC"      }    },    "pxCoverInsKey": "PEGAFW-KM-WORK KC-6",    "ArticleTitle": "5 Tips for traveling abroad",    "pzInsKey": "PEGAFW-KM-WORK KCP-165",    "AggregateRating": 0,    "ContentSourceURL": "http://",    "pyID": "KCP-165",    "pxCreateDateTime": "20190625T151857.614 GMT",    "RatingsCount": 0,    "pyLabel": "5 Tips for traveling abroad",    "mixedValueType": "",    "pxCreateOpName": "KM Admin",    "ArticleAbstract": "Whether you have traveled abroad many times, or are a nervous first-timer, everyone can use some tips for traveling abroad. People travel for business, vacation, family events, and many other reasons. Here are our top tips, of many, for making your travel abroad even better, no matter what you’re there for.",    "KMArticleLanguage": "en",    "LikePercentage": null,    "KMDiagnosticsId": "",    "ArticleViews": 0  }]

articles/KMRateArticle

Allows you to rate an article.

Method: POST

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMRateArticle

Query parameters

Response:

{  "ArticleID":"",  "ArticleRating":""
}

Sample response

{ 
  "ArticleID":"KCP-183",  "ArticleRating":"5"
}

search/KMGetArticlesAndPosts

Gets a list of articles or posts for a specified help site or community. If IsCombinedSearch is set to true, it returns both articles and posts for the help site or community.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMGetArticlesAndPosts

Query Parameters

Response

{
  "SearchedArticles": [
    {
      "AggregateRating": "",
      "ArticleAbstract": "",
      "ArticleID": "",
      "ArticleLanguage": "",
      "ArticleTitle": "",
      "ArticleViews": "",
      "ContentType": "",
      "CoverInsKey": "",
      "CreateDateTime": "",
      "InstanceHandleKey": "",
      "InternalContentOnly": "",
      "LikePercentage": "",
      "RatingsCount": "",
      "TaxonomyId": "",
      "TaxonomyLabel": ""
    }
  ],
  "SearchedPosts": [
    {
      "PostDescription": "",
      "PostTitle": ""
    }
  ]
} 

Sample Response

{
  "SearchedArticles": [    {             "AggregateRating": "0",             "ArticleAbstract": "Credit card fraud is when someone uses one or more of your cards without your permission. The thief may use your card to buy things or to take money out of an account. Fortunately, the law limits your financial liability in cases of credit card fraud.",             "ArticleID": "KCP-182",             "ArticleLanguage": "en",             "ArticleTitle": "Understanding fraudulent transactions",             "ArticleViews": "0",             "ContentType": "Authored",             "CoverInsKey": "PEGAFW-KM-WORK KC-20",             "CreateDateTime": "20190625T163738.336 GMT",             "InstanceHandleKey": "PEGAFW-KM-WORK KCP-182",             "InternalContentOnly": "false",             "LikePercentage": "",             "RatingsCount": "0",             "TaxonomyId": "",             "TaxonomyLabel": "Transactions"    },    {             "AggregateRating": "0",             "ArticleAbstract": "It isn't so easy to tell the difference, at least by looking at a Uplus Bank Credit Card today. In this article we answer a common question from younger new card applicants.",             "ArticleID": "KCP-208",             "ArticleLanguage": "en",             "ArticleTitle": "What is the difference between a credit card and a debit card?",             "ArticleViews": "0",             "ContentType": "Authored",             "CoverInsKey": "PEGAFW-KM-WORK KC-17",             "CreateDateTime": "20190625T173208.779 GMT",             "InstanceHandleKey": "PEGAFW-KM-WORK KCP-208",             "InternalContentOnly": "false",             "LikePercentage": "",             "RatingsCount": "0",             "TaxonomyId": "",
             "TaxonomyLabel": "Retail Banking"    }  ],  "SearchedPosts": [    {      "PostDescription": "<p> <span style=\"text-align: left; color: rgb(0, 0, 0); text-transform: none; text-indent: 0px; letter-spacing: normal; font-family: OpenSans, sans-se",      "PostTitle": "Looking for a high-rewards card"    }  ]}

articles/KMCreateArticleSuggestion

Creates an article suggestion in the Content candidates work basket.

Method: POST

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMCreateArticleSuggestion

Query parameters

Response

{"ArticleAbstract":"","ArticleTitle":"","KMContentCandidateCategoryID":"","KMContentCandidateCategoryLabel":"","KMContentSource":"","success":[  {           "message":""  } ]}

Sample response

{"ArticleAbstract":"Describe how rest APIs can be used","ArticleTitle":"How to use REST APIs?","KMContentCandidateCategoryID":"TAX-9","KMContentCandidateCategoryLabel":"General Q & A","KMContentSource":"Refer PegaKMREST service package for details","success":[{"message":"Article Suggestion successfully created"
}]}

downloads/KMDownloadAttachments/{AttachmentKey}

Downloads the attachment for a specified attachment key.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMDownloadAttachments/{AttachmentKey}

Path parameter

Response body

File in body

Response headers

content-disposition: attachment; filename="<filename>"
    content-type: application/octet-stream 

discussions/KMGetCommunityPostByID

Gets the post for a specified post ID and community name.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMGetCommunityPostByID

Query parameters

Response:

{    "CategoryID": "",
    "CategoryLabel": "",    "CommunitySiteKey": "",    "CreateDateTime": "",    "CreateOperatorName": "",    "Description": "",    "ModeratorBestAnswerID": "",    "ObjectType": "",    "PostID": "",    "PostTitle": "",    "Tags": [        {            "TagName": ""        }    ]}

Sample response

{    "CategoryID": "TAX-6",    "CategoryLabel": "",    "CommunitySiteKey": "PEGAFW-KM-DATA-COMMUNITYPORTAL UPLUS COMMUNITY!PUBLISHED",    "CreateDateTime": "20171024T092505.810 GMT",    "CreateOperatorName": "SARA CONNOR",    "Description": "<p> <span style=\"color: rgb(0, 0, 0); font-family: OpenSans, sans-serif; font-size: 13px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: 2; text-align: left; text-indent: 0px; text-transform: none; white-space: normal; widows: 2; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(255, 255, 255); text-decoration-style: initial; text-decoration-color: initial; display: inline !important; float: none;\"> Just curious about CD&#39;s, please help.</span> </p> ",    "ModeratorBestAnswerID": "",    "ObjectType": "",    "PostID": "C-1",    "PostTitle": "What's the most high-yield CD that U+ Bank offers?",    "Tags": [        {            "TagName": "cd"        },        {            "TagName": "certificate"        }    ]
}

discussions/KMGetCommunityPostsByCategory

Gets the posts related to a specified category ID and community name.

Method: GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMGetCommunityPostsByCategory

Query parameters

Response

{    "posts": [        {            "CategoryID": "",            "CategoryLabel": "",            "CreateDateTime": "",            "CreateOperator": "",            "Description": "",            "PostID": "",            "PostTitle": ""        }    ]}

Sample Response

{    "posts": [        {            "CategoryID": "TAX-9",            "CategoryLabel": "General Q & A",            "CreateDateTime": "20180412T154204.644 GMT",            "CreateOperator": "Moderator",            "Description": " <p> We have implementeda profantity filter on this site. I&#39;d like to know what people think about that. The intent is to help keep this site a safe place for open collaboration and avoid explicit or profane words (which we would mask out using aster+",            "PostID": "C-15",            "PostTitle": "Profanity filtering in this community"        },
        {            "CategoryID": "TAX-9",            "CategoryLabel": "General Q & A",            "CreateDateTime": "20180412T152307.003 GMT",            "CreateOperator": "Rebecca Biggs",            "Description": " <p>  <span style=\"font-size:14px;\">  <span style=\"color: rgb(0, 0, 0); font-family: OpenSans, sans-serif; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: 400; letter-spacing: normal; text-align: left; text-ind+",            "PostID": "C-14",            "PostTitle": "East Coast Colleges"        }    ]}

discussions/KMGetUserCommunityPost

Gets all the community posts for a specified operator ID.

Method:  GET

Sample endpoint URL:  https://<DomainName>/prweb/api/PegaKMREST/articles/KMGetUserCommunityPost

Query Parameters

Response

{    "posts": [        {            "categoryid": "",            "categoryname": "",            "communityname": "",            "memberemail": "",            "memberid": "",            "membername": "",            "postbody": "",            "postid": "",            "posttitle": ""        }     ]}

Sample response

{    "posts": [        {            "categoryid": "TAX-5",            "categoryname": "Retail Banking",            "communityname": "Uplus Community",            "memberemail": "",            "memberid": "CONNOR",            "membername": "Sara Connor",            "postbody": "<p> Time to start planning for college savings, and I&#39;m interested in learning about college savings.&nbsp; Any good sites that talk about 529 plans? Just had our first child!</p> \n\n<p> <img alt=\"\" height=\"100\" src=\"../datacontent/Image/rteImages/new+",            "postid": "C-9",            "posttitle": "Looking for good information on college savings plans"        },        {            "categoryid": "TAX-2",            "categoryname": "Customer Service",            "communityname": "Uplus Community",            "memberemail": "",            "memberid": "CONNOR",            "membername": "Sara Connor",            "postbody": "<p> <span style=\"color: rgb(0, 0, 0); font-family: OpenSans, sans-serif; font-size: 13px; font-style: normal; font-variant-ligatures: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: 2; text-align: left; text-inden+",            "postid": "C-6",            "posttitle": "How do I change my contact details?"        }    ]}