Zendesk Guide knowledge base API: The complete developer guide for 2026
Stevia Putri
Last edited February 25, 2026
If you are building integrations with Zendesk or looking to programmatically manage your knowledge base content, the Zendesk Help Center API (often called the Zendesk Guide knowledge base API) is your gateway. Whether you need to sync articles to an external search system, build a backup solution, or feed content into an AI knowledge base, this REST API provides the tools to get it done.
Let's break down how it works and how to use it effectively.
What is the Zendesk Guide knowledge base API?
The Zendesk Help Center API is a REST API that lets you programmatically manage content in your Zendesk Guide knowledge base. It is part of Zendesk's broader API ecosystem and uses JSON for both requests and responses.
Here's what you can do with it:
- Read content fetch articles, sections, and categories for external use
- Write content create, update, and archive articles programmatically
- Manage translations handle multilingual content at scale
- Search and filter find specific content using labels, dates, and other criteria
The API follows standard REST conventions. Your base URL looks like https://{your-subdomain}.zendesk.com/api/v2/help_center/, and all responses are filtered according to the permissions of the user making the request. This means anonymous users only see public content, while agents can access internal articles depending on their permissions.
Getting started with authentication
Before you can make any API calls, you need to authenticate. Zendesk offers two main methods: API tokens and OAuth 2.0.
API token authentication (recommended for server-side scripts)
API tokens are the simplest way to get started. You generate them in your Zendesk Admin Center under Apps and integrations > APIs > Zendesk API.
| Attribute | Detail |
|---|---|
| Token limit | 256 per account (up to 2,048 for larger accounts) |
| Format | {email_address}/token:{api_token} |
| Header | Authorization: Basic {base64_encoded_credentials} |
Here's how it looks in practice:
curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
-u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv
The -u flag in cURL automatically handles the Base64 encoding for you. If you are building the header manually in code, combine your email and token with a colon, Base64-encode the result, and add it to the Authorization header.
OAuth 2.0 (for user-facing applications)
If you are building a client-side application or need to act on behalf of individual users, OAuth is the better choice. It uses Bearer tokens:
curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
-H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"
The key advantage here is that OAuth supports CORS, making it suitable for browser-based applications. API tokens do not support CORS and are limited to server-side use.
Security note: All connections must use TLS 1.2 or higher. Store your tokens securely and never commit them to version control.
Core API endpoints and operations
The Help Center API is organized around three main content types: categories, sections, and articles. Think of it as a hierarchy: categories contain sections, and sections contain articles.
Working with articles
The articles endpoint is where you will spend most of your time. Here are the key operations:
List all articles:
GET /api/v2/help_center/articles.json
This returns a paginated list of articles. You can filter results using query parameters:
| Parameter | Purpose | Example |
|---|---|---|
label_names | Filter by labels | ?label_names=faq,billing |
sort_by | Sort field | ?sort_by=updated_at |
sort_order | Sort direction | ?sort_order=desc |
start_time | Incremental export | ?start_time=1704067200 |
Get a specific article:
GET /api/v2/help_center/articles/{article_id}.json
Create an article:
POST /api/v2/help_center/sections/{section_id}/articles.json
Required fields include title, locale, and permission_group_id. You can also set optional fields like body (HTML content), author_id, label_names, and draft status.
Update an article:
PUT /api/v2/help_center/articles/{article_id}.json
Archive an article:
DELETE /api/v2/help_center/articles/{article_id}.json
Content hierarchy endpoints
| Endpoint | Purpose |
|---|---|
GET /api/v2/help_center/categories.json | List all categories |
GET /api/v2/help_center/categories/{id}/sections.json | List sections in a category |
GET /api/v2/help_center/sections.json | List all sections |
GET /api/v2/help_center/sections/{id}/articles.json | List articles in a section |
Sideloading related data
One useful feature is sideloading, which lets you include related data in a single request. Add ?include=users,sections,categories to your articles request, and the response will include full objects for authors, sections, and categories instead of just IDs.
Handling pagination efficiently
Pagination is where many developers hit their first snag. The Help Center API supports two pagination methods, and choosing the right one matters.
Cursor-based pagination (recommended)
Cursor pagination is the modern approach and performs significantly better with large datasets. To use it, add page[size] to your request:
GET /api/v2/help_center/articles.json?page[size]=100
The response includes a meta object with a has_more boolean and a links object with next and prev URLs:
{
"articles": [...],
"meta": {
"has_more": true
},
"links": {
"next": "https://.../articles.json?page[size]=100&page[after]=xxx",
"prev": null
}
}
Keep following the next URL until has_more is false. Here is a Python example:
import requests
from base64 import b64encode
def fetch_all_articles(subdomain, email, token):
base_url = f"https://{subdomain}.zendesk.com/api/v2/help_center/articles.json"
credentials = b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {credentials}"}
articles = []
url = f"{base_url}?page[size]=100"
while url:
response = requests.get(url, headers=headers)
data = response.json()
articles.extend(data["articles"])
url = data["links"]["next"] if data["meta"]["has_more"] else None
return articles
Offset-based pagination (legacy)
Offset pagination still works but has limitations. As of August 2023, you cannot retrieve more than 10,000 records (100 pages) using this method. If you try, you will get a 400 Bad Request error.
GET /api/v2/help_center/articles.json?per_page=100&page=2
The response includes next_page and previous_page URLs. Stop when next_page is null.
Bottom line: Use cursor pagination for new integrations. It is faster, more reliable, and has no hard limits.
Common integration patterns
Now that you understand the basics, let's look at how developers typically use this API in production.
External search indexing
A common use case is indexing your Zendesk articles in an external search engine like Elasticsearch or Algolia. The pattern looks like this:
- Fetch all articles using cursor pagination
- Transform the HTML body to plain text (strip tags)
- Index the article ID, title, body text, and URL
- Set up a periodic sync using the
start_timeparameter for incremental updates
The key is preserving the original article URL in your index so search results can link back to Zendesk.
Content backup and migration
For backup workflows, you might want to export your entire knowledge base:
- Iterate through all categories
- For each category, get its sections
- For each section, get its articles
- Save the full article objects (including HTML body) to your backup storage
This preserves your content hierarchy and makes restoration straightforward.
AI and RAG system integration
A growing use case is feeding Zendesk content into Retrieval-Augmented Generation (RAG) systems for AI-powered support. The workflow typically involves:
- Extracting articles via the API
- Converting HTML to Markdown or plain text
- Chunking the content for vector storage
- Preserving the original URL for citations
This is where tools like eesel AI can help. Instead of building custom ETL pipelines, you can connect your Zendesk account directly and have an AI agent that answers questions using your knowledge base content, complete with citations back to the original articles.
Rate limits and best practices
Understanding rate limits prevents your integration from hitting walls at scale.
Request limits by plan
| Plan | Support/Help Center API Limit |
|---|---|
| Suite Team | 200 requests/minute |
| Suite Growth | 400 requests/minute |
| Suite Professional | 400 requests/minute |
| Suite Enterprise | 700 requests/minute |
| Suite Enterprise Plus | 2,500 requests/minute |
Source: Zendesk Rate Limits Documentation
Handling rate limit errors
When you exceed the limit, the API returns a 429 status code with a Retry-After header indicating how many seconds to wait. Your code should:
- Check for 429 responses
- Extract the
Retry-Aftervalue - Wait that many seconds before retrying
- Consider implementing exponential backoff for repeated failures
Here is a simple retry decorator in Python:
import time
import requests
from functools import wraps
def with_rate_limit_retry(func):
def wrapper(*args, **kwargs):
max_retries = 3
for attempt in range(max_retries):
response = func(*args, **kwargs)
if response.status_code != 429:
return response
retry_after = int(response.headers.get("Retry-After", 60))
time.sleep(retry_after)
raise Exception("Rate limit exceeded after retries")
return wrapper
def api_call(url, headers):
return requests.get(url, headers=headers)
Performance tips
- Use cursor pagination it is faster and has no 10,000 record limit
- Enable sideloading fetch related data in one request instead of making multiple calls
- Cache aggressively article content does not change that frequently
- Use incremental exports the
start_timeparameter lets you fetch only changed content
Alternative approaches to consider
Building a custom API integration is not always the right choice. Here is a quick framework for deciding:
Use the API directly when:
- You need complete control over data transformation
- You have dedicated engineering resources
- Your use case is unique or complex
Use Zendesk's native features when:
- You just want to surface external content in search use federated search
- You need basic content management use the built-in UI
Use an integration platform when:
- You want AI-powered answers without building RAG pipelines
- You need quick setup without engineering resources
- You want continuous syncing without maintenance overhead
This is where eesel AI fits in. Rather than writing custom scripts to extract, transform, and sync your Zendesk content, you can connect your account in minutes and get an AI teammate that answers customer questions using your knowledge base. It handles the API integration, content indexing, and answer generation, letting you focus on higher-value work.
Build powerful knowledge integrations with Zendesk
The Zendesk Help Center API gives you the building blocks to create sophisticated knowledge management workflows. Whether you are building a custom search index, migrating content between systems, or feeding articles into AI platforms, understanding authentication, pagination, and rate limits sets you up for success.
Start small: fetch a list of articles, experiment with pagination, then build up to more complex integrations. And if you find yourself spending more time maintaining data pipelines than solving business problems, consider whether an integration platform might be a better fit.
If you are looking to enhance your Zendesk setup with AI capabilities, eesel AI offers a direct integration that turns your knowledge base into an intelligent support agent. No custom API development required.
