Zendesk Guide knowledge base API: The complete developer guide for 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.

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:

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

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:

1. Fetch all articles using cursor pagination
2. Transform the HTML body to plain text (strip tags)
3. Index the article ID, title, body text, and URL
4. Set up a periodic sync using the start_time parameter 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:

1. Iterate through all categories
2. For each category, get its sections
3. For each section, get its articles
4. 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:

1. Extracting articles via the API
2. Converting HTML to Markdown or plain text
3. Chunking the content for vector storage
4. 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

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:

1. Check for 429 responses
2. Extract the Retry-After value
3. Wait that many seconds before retrying
4. 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):
    @wraps(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

@with_rate_limit_retry
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_time parameter 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.