Articles List

Get a page of online articles for the given language and category through either search or query. This resource is available in REST API version 38.0 and later.

Syntax

URI: /services/data/vXX.X/support/knowledgeArticles

Method: GET

Formats: JSON, XML

Authentication: Authorization: Bearer token

HTTP headers

Accept: Optional. Can be either application/json or application/xml.

Accept-language: Required. The article must be an active language in the user’s organization

If the language code isn’t valid, an error message is returned: “The language code is not valid or not supported by Knowledge.”
If the language code is valid, but not supported by Knowledge, then an error message is returned: “Invalid language code. Check that the language is included in your Knowledge language settings.”

Input:

string q: Optional, Performs an SOSL search. If the query string is null, empty, or not given, an SOQL query runs.

The characters ? and * are used for wildcard searches. The characters (, ), and " are used for complex search terms. See FIND {SearchQuery}.

string channel: Optional, defaults to user’s context.

App: Visible in the internal Salesforce Knowledge application
Pkb: Visible in the public knowledge base
Csp: Visible in the Customer Portal
Prm: Visible in the Partner Portal

string categories in map json format {“group1”:”category1”,”group2”:”category2”,...} )

Optional, defaults to None. Category group must be unique in each group:category pair, otherwise you get ARGUMENT_OBJECT_PARSE_ERROR. There is a limit of three data category conditions, otherwise you get INVALID_FILTER_VALUE.

string queryMethod values are: AT, BELOW, ABOVE, ABOVE_OR_BELOW. Only valid when categories are specified, defaults to ABOVE_OR_BELOW.

string sort: Optional, a sortable field name LastPublishedDate, CreatedDate, Title, ViewScore. Defaults to LastPublishedDate for query and relevance for search.

When sorting on ViewScore it is only available for query, not search, and no pagination is supported. You only get one page of results.

Note

string order: Optional, either ASC or DESC, defaults to DESC. Valid only when sort is valid.

integer pageSize: Optional, defaults to 20. Valid range 1 to 100.

integer pageNumber : Optional, defaults to 1.

Output:

A page of online articles in the given language and category visible to the current user.

Article Page

A page of articles. The individual entries are article summaries so the size can be kept at a minimum.

1{
2   "articles": [ Article Summary, … ],  // list of articles
3      "currentPageUrl": URL,   // the article list API with current page number
4        "nextPageUrl": URL,  // the article list API with next page number,
5      which can be null if there are no more articles.
6      "pageNumber": Int  // the current page number, starting at 1.
7    }

The API supports paging. Each page of responses includes a URL to its page, as well as the URL to the next page of articles.

Note

if the user input parameter has the default value, the API does not show this parameter in either currentPageUrl or nextPageUrl.

Note

Article Summary

A summary of an article used in a list of article responses. It shares similar properties to the Article Detail representation, as one is a superset of the other.

1{
2      "id":  Id,    // articleId
3      "articleNumber": String,  
4      "articleType": String,  // apiName of the article type, available in API v44.0 and later
5      "title":  String,
6      "urlName": String,  // available in API v44.0 and later
7      "summary":  String,
8      "url":  URL,  // to the Article Detail API
9      "viewCount": Int,       // view count in the interested channel
10      "viewScore": double (in xxx.xxxx precision),   // view score in the interested channel.
11      "upVoteCount": int,  // up vote count in the interested channel. 
12      "downVoteCount": int, // down vote count in the interested channel.
13      "lastPublishedDate": Date // last publish date in ISO8601 format
14      "categoryGroups":  [ Data Category Group, …. ]}

The “url” property always points to the Article Details resource endpoint. For information on valid channel values, see the channel parameter description

Data Category Group

An individual data category group, its root category, and a list of selected data categories in the group.

1{
2      "groupName": String,  // the unique name of the category group
3      "groupLabel": String,  // returns the translated version
4      "selectedCategories": [ Data Category Summary, … ]
5    }

Data Category Summary

Provides a summary of data category information. The Summary and Detail responses share common properties.

1{
2            "categoryName": String, // the unique name of the category
3            "categoryLabel":  String, // returns the translated version, per the API language specified
4            "url":  String // returns the url for the DataCategory REST API.
5    }

The outputs of Data Category Group and Data Category Summary in Article List API are different from the Data Category Groups API.

Note

Example

Example Request

1curl https://MyDomainName.my.salesforce.com/services/data/v68.0/support/knowledgeArticles?sort=ViewScore&channel=Pkb&pageSize=3
2    HTTP Headers:
3        Content-Type: application/json; charset=UTF-8
4        Accept: application/json
5        Accept-Language: en-US

Example Response Body

1{
2 "articles" : [ {
3	"articleNumber" : "000001002",
4	"categoryGroups" : [ ],
5	"downVoteCount" : 0,
6	"id" : "kA0xx000000000BCAQ",
7	"lastPublishedDate" : "2015-02-25T02:07:18Z",
8	"summary" : "With this online Chinese input tool, you can type Chinese characters through your web browser without installing any Chinese input software in your system. The Chinese online input tool uses the popular Pin Yin input method. It is a fast and convenient tool to input Chinese on English OS environments.",
9	"title" : "Long text test",
10	"upVoteCount" : 0,
11	"url" : "/services/data/v68.0/support/knowledgeArticles/kA0xx000000000BCAQ",
12	"viewCount" : 4,
13	"viewScore" : 100.0
14 }, {
15	"articleNumber" : "000001004",
16	"categoryGroups" : [ ],
17	"downVoteCount" : 0,
18	"id" : "kA0xx000000000LCAQ",
19	"lastPublishedDate" : "2016-06-21T21:11:02Z",
20	"summary" : "The number of characters required for complete coverage of all these languages' needs cannot fit in the 256-character code space of 8-bit character encodings, requiring at least a 16-bit fixed width encoding or multi-byte variable-length encodings. \r\n\r\nAlthough CJK encodings have common character sets, the encodings often used to represent them have been developed separately by different East Asian governments and software companies, and are mutually incompatible. Unicode has attempted, with some controversy, to unify the character sets in a process known as Han unification.\r\n\r\nCJK character encodings should consist minimally of Han characters p",
21	"title" : "Test Images",
22	"upVoteCount" : 0,
23	"url" : "/services/data/v68.0/support/knowledgeArticles/kA0xx000000000LCAQ",
24	"viewCount" : 0,
25	"viewScore" : 0.0
26 }, {
27	"articleNumber" : "000001012",
28	"categoryGroups" : [ ],
29	"downVoteCount" : 0,
30	"id" : "kA0xx000000006GCAQ",
31	"lastPublishedDate" : "2016-06-21T21:10:48Z",
32	"summary" : null,
33	"title" : "Test Draft 2",
34	"upVoteCount" : 0,
35	"url" : "/services/data/v68.0/support/knowledgeArticles/kA0xx000000006GCAQ",
36	"viewCount" : 0,
37	"viewScore" : 0.0
38 } ],
39 "currentPageUrl" : "/services/data/v68.0/support/knowledgeArticles?channel=Pkb&amp;pageSize=3&amp;sort=ViewScore",
40 "nextPageUrl" : null,
41 "pageNumber" : 1
42}

Usage

Salesforce Knowledge must be enabled in your organization. This resource can be used in API version 38.0 and later. The Custom File Field is not supported because it returns a link to a binary stream. Use the language code format used in Which Languages Does Salesforce Support?.

Valid channel Values

When using the options string channel, where the matching articles are visible, the following values are valid.
- App–Visible in the internal Salesforce Knowledge application
- Pkb–Visible in the public knowledge base
- Csp–Visible in the Customer Portal
- Prm–Visible in the Partner Portal
If channel isn’t specified, the default value is determined by the type of user.
- Pkb for a guest user
- Csp for a Customer Portal user
- Prm for a Partner Portal user
- App for any other type of user
If channel is specified, the specified value may be used to retrieve articles.
- For guest, Customer Portal, and Partner Portal users, if the specified channel is other than the channel accessible to the user, an error is returned.
- For all users other than guest, Customer Portal, and Partner Portal users, the specified channel value is used.