This is the reference documentation for the Zendesk Help Center API.

The Help Center API is part of the Zendesk v2 API. Any general mechanisms and conventions, such as pagination and authentication, work as described in the Zendesk v2 API documentation and are considered implied in this text.

Responses are always filtered according to the permissions of the user on whose behalf the API request is made. For example, when the user requests a list of articles in a section, the API returns only the articles the user can view in Help Center.

The API deals only with Help Center items. For example, comments can be made on both articles and requests, but the Help Center API only provides access to article comments. This means that an endpoint that returns "all comments made by a user" actually returns "all comments made on Help Center articles by a user."

If you have multiple brands, you must use the brand-specific subdomain in the API requests. For example, if you have a brand named brand1, a request for information about that brand's help center content might look like https://brand1.zendesk.com/api/v2/help_center/....

Data types

  • The documentation specifies using integers for IDs in the API. The term refers to the JSON numeric type, not a C-like int data type. Zendesk recommends using the string type for IDs in Help Center.

  • Locales are returned and passed as strings. Example: 'en-us'.

  • Time stamps are in the ISO 8601 format. Example: '2015-04-16T09:14:57Z'.

Pagination

The Help Center API supports two methods of paginating through results -- cursor pagination and offset pagination. Cursor-based pagination is available in a subset of endpoints but Zendesk recommends using it instead of offset pagination when available. Cursor pagination provides greatly improved performance when working with large record sets. See Comparing Cursor Pagination and Offset Pagination for further details on the differences between the pagination methods. Check the endpoint docs to see if one of the pagination methods is not supported.

Using cursor-based pagination

To use cursor-based pagination, use the page[size] query parameter in the initial request to specify the number of items to return per page. For most endpoints, this can't be set to more than 100. If you omit the page[size] parameter, offset pagination is used.

After the initial request, use the links in the response to get the next page of results.

For example, a request to the articles endpoint with the URL https://example.zendesk.com/api/v2/help_center/articles.json?page[size]=100 would return a response with the following format:

"articles": [ ... ],"meta": {  "has_more": true,  "after_cursor": "xxx",  "before_cursor": "yyy"},"links": {  "first": "https://example.zendesk.com/api/v2/help_center/articles?page[size]=100",  "last": "https://example.zendesk.com/api/v2/help_center/articles?page[before]=bGFzdF9wYWdl\u0026page[size]=100",  "next": "https://example.zendesk.com/api/v2/help_center/articles?page[size]=100&page[after]=xxx"}

The values "xxx" and "yyy" represent cursors.

Use the next link to retrieve the next page of results. Using the example above, make a request to https://example.zendesk.com/api/v2/help_center/articles.json?page[size]=100&page[after]=xxx to retrieve the next page of results.

The next link is also available in the "Link" HTTP response header. Example:

Link: <https://example.com/api/v2/help_center/en-us/articles?page%5Bafter%5D=xxx&page%5Bsize%5D=100>; rel="next"

Repeat the request until the has_more property of the meta object is false. This indicates there are no further records and you should stop paginating.

You can also paginate backwards. Follow the last link to jump to the final page. Then, as long as has_more is true, follow the prev link to step backwards one page at a time until has_more is false. Like the next link, the prev link is also available in the "Link" HTTP response header.

Using offset pagination

Offset pagination works as described in Using offset pagination in the Support API documentation. Most Help Center list requests return 30 records per page by default when using offset pagination. You can change the number on a per-request basis by including a per_page parameter in the request's query string. Example: per_page=100. However, you can't exceed 100 records per page for most requests.

Rate limits

This Help Center API is rate limited. Only a certain number of requests are allowed per minute. Zendesk reserves the right to adjust the rate limit for given endpoints to provide a high quality of service for all clients.

The Help Center API follows the Support API's requests-per-minute limits. See Rate Limits in the Support API. Requests in one API don't count against the rate limit of the other API.

If the rate limit is exceeded, Zendesk responds with an HTTP 429 Too Many Requests response code and a body that details the reason for the rate limiter kicking in. The response has a Retry-After header that tells you how many seconds to wait before trying again. You can use the information in your API client to handle errors. See Best practices for avoiding rate limiting.