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."
- The documentation specifies using integers for IDs in the API. The term refers to the JSON numeric type, not a C-like
intdata 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'.
The Help Center API supports two methods of paginating through results -- cursor pagination and offset pagination. Zendesk recommends using cursor pagination instead of offset pagination where possible. 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.
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": [ ... ],
The values "xxx" and "yyy" represent cursors.
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.
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.
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.
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.