Zendesk Guide API content management: A complete developer guide

Managing help center content at scale gets tedious when you're doing it manually. Whether you're migrating articles from another platform, syncing assets from your marketing team, or organizing content across multiple brands, the Zendesk Guide API gives you programmatic control over your knowledge base.

This guide walks you through everything you need to know about Zendesk Guide API content management. We'll cover authentication, core endpoints, practical implementation patterns, and when it makes sense to use the API versus alternatives like eesel AI.

What you'll need

Before diving in, make sure you have:

• A Zendesk account with Guide enabled (Suite Team plan or higher)
• Admin access to generate API tokens
• Basic familiarity with REST APIs and JSON
• Your preferred HTTP client (cURL, Postman, or a programming language like Python)

Understanding Zendesk Guide API authentication

The Zendesk Guide API uses the same authentication patterns as other Zendesk APIs. Here's what you'll need to know.

API token authentication (recommended)

API tokens are the simplest way to authenticate. You'll generate them in Admin Center under Apps and integrations > APIs > Zendesk API.

Important details:

• Format your credentials as {email_address}/token:{api_token}
• Base64 encode the entire string for the Authorization header
• You can have up to 256 active tokens (2048 for legacy accounts)
• Tokens can impersonate any user, including admins, so keep them secure

Example cURL request:

curl https://{subdomain}.zendesk.com/api/v2/guide/medias \
  -v -u {email_address}/token:{api_token}

OAuth for multi-customer apps

If you're building an integration that'll be distributed to multiple Zendesk customers, you'll need to use OAuth instead of API tokens. Regular API tokens won't work for apps that need to authenticate across different Zendesk instances.

Rate limits and SSL

Most endpoints allow 700 requests per minute. If you hit the limit, you'll get a 429 status code. All requests must use HTTPS with TLS 1.2 or higher.

Core content management endpoints

The Guide API offers several endpoints for managing different types of content. Let's break down the most useful ones.

Guide Medias API

The Guide Medias API handles file uploads and media management for your Zendesk help center. This is essential when you want to programmatically add images or attachments to articles.

The 3-step upload process:

1. Request an upload URL POST to /api/v2/guide/medias/upload_url with content type and file size
2. Upload the file PUT the file to the signed URL returned in step 1
3. Create the media object POST to /api/v2/guide/medias with the asset upload ID

Files can be up to 20MB. The API uses ULID-based identifiers, which are sortable unlike traditional UUIDs.

Python example:

import requests
import base64

auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
headers = {"Authorization": f"Basic {auth}", "Content-Type": "application/json"}

upload_data = {"content_type": "image/png", "file_size": 12345}
response = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias/upload_url",
    json=upload_data,
    headers=headers
)
upload_url = response.json()["upload_url"]["url"]
asset_id = response.json()["upload_url"]["asset_upload_id"]

media_data = {"asset_upload_id": asset_id, "filename": "screenshot.png"}
media = requests.post(
    f"https://{subdomain}.zendesk.com/api/v2/guide/medias",
    json=media_data,
    headers=headers
)

Content Tags API

Content tags help you organize articles and posts. The Content Tags API lets you create, update, and manage tags programmatically.

Key capabilities:

• Create and manage tags with POST/PUT/DELETE requests
• Batch operations via /api/v2/guide/content_tags/jobs (delete or merge tags)
• Filter tags by name prefix
• Sort by ID or name in ascending or descending order

Batch operations are useful for cleanup tasks, like merging duplicate tags or removing outdated ones across your entire knowledge base.

Dynamic Content API

If you support multiple languages, the Dynamic Content API is essential. It manages localized content variants using placeholders like {{dc.password_reset_instructions}}.

How it works:

• Each dynamic content item has a default locale and multiple variants
• Variants contain the actual translated text
• Zendesk automatically serves the right variant based on the user's locale
• Falls back to the default if no matching variant exists

Note: Dynamic content requires a Professional plan or higher.

External Content Sources API

The External Content Sources API enables federated search, letting you pull results from external systems into your help center search.

Use cases:

• Indexing content from a learning management system
• Including forum posts in search results
• Making Jira issues searchable from the help center

This requires Help Center manager permissions and works with Zendesk's crawler to index external content.

Practical implementation: Automating media uploads

Let's look at a real-world scenario. Your marketing team creates screenshots in Figma and saves them to Google Drive. You want these automatically added to your Zendesk media gallery so writers can use them in articles.

Here's a complete Python implementation:

import requests
import base64
import time

class ZendeskMediaUploader:
    def __init__(self, subdomain, email, token):
        self.subdomain = subdomain
        self.base_url = f"https://{subdomain}.zendesk.com/api/v2"
        self.auth = base64.b64encode(f"{email}/token:{token}".encode()).decode()
        self.headers = {
            "Authorization": f"Basic {self.auth}",
            "Content-Type": "application/json"
        }

    def upload_file(self, file_path, content_type):
        """Upload a file to Zendesk media gallery."""
        file_size = os.path.getsize(file_path)
        filename = os.path.basename(file_path)

        # Step 1: Get upload URL
        upload_data = {"content_type": content_type, "file_size": file_size}
        resp = requests.post(
            f"{self.base_url}/guide/medias/upload_url",
            json=upload_data,
            headers=self.headers
        )
        resp.raise_for_status()

        upload_info = resp.json()["upload_url"]

        # Step 2: Upload file to signed URL
        with open(file_path, "rb") as f:
            put_headers = {
                "Content-Disposition": upload_info["headers"]["Content-Disposition"],
                "Content-Type": content_type,
                "X-Amz-Server-Side-Encryption": "AES256"
            }
            put_resp = requests.put(upload_info["url"], data=f, headers=put_headers)
            put_resp.raise_for_status()

        # Step 3: Create media object
        media_data = {
            "asset_upload_id": upload_info["asset_upload_id"],
            "filename": filename
        }
        media_resp = requests.post(
            f"{self.base_url}/guide/medias",
            json=media_data,
            headers=self.headers
        )
        media_resp.raise_for_status()

        return media_resp.json()["media"]

Error handling tips:

• 401 Unauthorized: Check your token and email format (must include /token)
• 403 Forbidden: Verify you have Guide manager permissions
• 409 Conflict: Retry the request (transient error)
• 429 Rate Limited: Implement exponential backoff

When to use the Zendesk Guide API vs. alternatives

The API isn't always the right choice. Here's how you'll decide.

Use the API when:

• You need to migrate large amounts of content from another platform
• You're building a custom integration with your existing tools
• You want to automate repetitive tasks (like bulk tagging)
• You have developer resources available for ongoing maintenance

Consider native Zendesk features when:

• You only need occasional manual uploads
• Your team is comfortable working in the Zendesk interface
• Federated search meets your external content needs without code

Consider integration platforms when:

• You need simple automation without custom code
• Your use case fits standard triggers and actions
• You want something running quickly without development time

Consider eesel AI when:

You might want to look at eesel AI if your goal is to make your Zendesk knowledge base smarter without building custom integrations. Instead of writing scripts to sync content, eesel connects directly to Zendesk, Confluence, Google Docs, and other sources.

Here's the difference: the Guide API lets you move content into Zendesk programmatically. eesel AI indexes your content where it lives and makes it accessible to your support team through an AI Agent that works inside Zendesk. You don't migrate anything. You don't write code. You connect your sources and the AI learns from them.

For teams without dedicated developers, this can be a faster path to unified knowledge. Our pricing starts at $299/month for the Team plan, which includes up to 3 bots and 1,000 AI interactions.

Best practices and troubleshooting

Security

• Store API tokens in environment variables, never in your code
• Rotate tokens regularly (Zendesk lets you have up to 256, so you can create new ones before deleting old)
• Use separate tokens for different integrations so you can revoke one without affecting others

Pagination

List endpoints return paginated results. Use cursor-based pagination for large datasets (it's more reliable than offset pagination for changing data):

params = {"page[size]": 100}
while True:
    resp = requests.get(url, params=params, headers=headers)
    data = resp.json()

    # Process records
    for record in data["records"]:
        process(record)

    # Check for more pages
    if not data["meta"]["has_more"]:
        break
    params["page[after]"] = data["meta"]["after_cursor"]

Testing

• Test in a sandbox environment before running against production
• Use the Postman collection from Zendesk to explore endpoints
• Log API responses during development to understand error conditions

Common pitfalls

• Forgetting the /token suffix in the email address
• Not Base64 encoding the credentials
• Hitting rate limits during bulk operations
• Not handling 409 conflicts with retry logic

Start managing Zendesk content more efficiently

The Zendesk Guide API gives you powerful tools for content management at scale. Whether you're automating media uploads, organizing content with tags, or building multi-language support, the API provides the primitives you need.

But building custom integrations isn't the only path. If you want to unify your knowledge sources without writing code, eesel AI offers an alternative. Our AI Agent connects to Zendesk and learns from your existing documentation wherever it lives, no migration required.

The right choice depends on your team's technical resources and specific needs. If you have developers and unique requirements, the Guide API is a solid foundation. If you want to get up and running quickly with AI-powered support, explore what eesel AI can do for your Zendesk setup.