Skip to main content

         This documentation site is for previous versions. Visit our new documentation site for current releases.      

Pega Knowledge REST APIs

Updated on January 20, 2022

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:

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.


    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

    ArticleTitle*stringThe title of the article.
    ArticleAbstract*stringThe abstract for the article.
    CategoryIDsstringThe Category IDs (for example, TAX-1, TAX-2). If no category is passed, the default is "UNCAT".
    ContentType*stringThe Content type (Values: "Authored" or "URL").
    ContentURLstringThe URL of a resource if the content type is URL.
    ContentBodystringThe Content body (HTML or plain text).
    IsInternalContentstringTrue or False. False is the default.
    TagsListstringComma-separated tag names.
    ArticleLanguage*stringThe master language code of the article.

    * 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

    ArticleTitleThis is a REST API demo.
    Article AbstractThis is a REST API demo.
    TagsListapi, rest

    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"
    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?
    HTTP/1.1Authorization: Bearer
    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=------------------------------
    Content-Length: 38817 -----------------------54197066538882863805869
    Content-Disposition: form-data; name="file";filename="0.jpg"
    Content-Disposition: form-data; name="Body"
    this is text for article body

    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.

    Error conditionError message
    The article title is empty."Article title cannot be empty"
    The article abstract is empty."Article abstract cannot be empty"
    The ContentType is empty or is not equal to "Authored" or "URL""Content type can only be "Authored" or "URL" and is case-sensitive" 
    The content type is URL and URL is empty, or the content type is set to "Authored" and the content body is empty."For content type "URL", URL field cannot be empty and for content type "Authored", Content body cannot be empty"
    The article language is empty. "Article language cannot be empty"
    The language does not exist in the system."Language code should exist in the system"
    The Category ID does not exist in the system."CategoryID doesn't exist" 
    An article already exists with the same title."Article title already exists"
    The Rate Limiting has been exceeded."Rejecting request s number of requests exceeded threshold"

    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:

    Error conditionError message
    The file size is greater than 5MB"Failed: File size greater than 5MB"
    More than five files are sent"Number of file attachments exceeded the maximum limit of 5 for article "article ID"
    Attachment type is restricted"FileType not allowed"

    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.

    The implementation team configures the virus stub utility.


    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

    ArticleIdstringThe pyld of the published content.


    {  "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=\"\" onclick=\", '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": " 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"    }  ]}


    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

    TaxKeystringThe Taxonomy ID associated with the articles.


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


    Allows you to rate an article.

    Method: POST

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

    Query parameters

    ArticleIDstringThe ID of the article to rate.
    RatingstringA rating between 1 and 5.
    UserIdstringThe Operator ID.


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

    Sample response

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


    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

    SearchTextstringThe text to search for.
    SiteNamestringThe name of the help site or community site.
    IsHelpSitestringIs "SiteName" a help site?
    IsCombinedSearchstringIs this a combined search?


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


    Creates an article suggestion in the Content candidates work basket.

    Method: POST

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

    Query parameters

    articletitlestringThe title of the article.
    articleabstractstringThe abstract for the article.
    categoryidstringThe Category ID; only one category is allowed.
    articlebodystringThe article body (HTML or plain text).
    tagsstringComma separated tag names.


    {"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 the attachment for a specified attachment key.

    Method: GET

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

    Path parameter

    AttachmentKeystringThe key of the Data-WorkAttach-File instance.

    Response body

    File in body

    Response headers

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


    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

    PostIdstringThe ID of the post.
    CommunityNamestringThe name of the community.


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


    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

    CategoryIDstringThe Category ID for which posts should be retrieved.
    CommunityNamestringThe Community name.


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


    Gets all the community posts for a specified operator ID.

    Method:  GET

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

    Query Parameters

    UserIDstringThe ID of the Operator whose posts you want to retrieve.


    {    "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?"        }    ]}
    • Previous topic Adding a service case to the Pega Knowledge troubleshooter

    Have a question? Get answers now.

    Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

    Did you find this content helpful?

    Want to help us improve this content?

    We'd prefer it if you saw us at our best. is not optimized for Internet Explorer. For the optimal experience, please use:

    Close Deprecation Notice
    Contact us