Zendesk Guide Wissensdatenbank-API: Der vollständige Entwicklerleitfaden für 2026

Wenn Sie Integrationen mit Zendesk erstellen oder Ihre Wissensdatenbankinhalte programmgesteuert verwalten möchten, ist die Zendesk Help Center API (oft als Zendesk Guide Wissensdatenbank-API bezeichnet) Ihr Tor. Egal, ob Sie Artikel mit einem externen Suchsystem synchronisieren, eine Backup-Lösung erstellen oder Inhalte in eine KI-Wissensdatenbank einspeisen müssen, diese REST-API bietet die Werkzeuge, um dies zu erledigen.

Lassen Sie uns aufschlüsseln, wie sie funktioniert und wie Sie sie effektiv nutzen können.

Was ist die Zendesk Guide Wissensdatenbank-API?

Die Zendesk Help Center API ist eine REST-API, mit der Sie Inhalte in Ihrer Zendesk Guide Wissensdatenbank programmgesteuert verwalten können. Sie ist Teil des breiteren API-Ökosystems von Zendesk und verwendet JSON sowohl für Anfragen als auch für Antworten.

Folgendes können Sie damit tun:

• Inhalte lesen - Artikel, Abschnitte und Kategorien für die externe Verwendung abrufen
• Inhalte schreiben - Artikel programmgesteuert erstellen, aktualisieren und archivieren
• Übersetzungen verwalten - mehrsprachige Inhalte in großem Umfang verarbeiten
• Suchen und filtern - bestimmte Inhalte mithilfe von Labels, Datumsangaben und anderen Kriterien finden

Die API folgt den Standard-REST-Konventionen. Ihre Basis-URL sieht wie https://{Ihre-Subdomain}.zendesk.com/api/v2/help_center/ aus, und alle Antworten werden gemäß den Berechtigungen des Benutzers gefiltert, der die Anfrage stellt. Dies bedeutet, dass anonyme Benutzer nur öffentliche Inhalte sehen, während Agenten je nach ihren Berechtigungen auf interne Artikel zugreifen können.

Erste Schritte mit der Authentifizierung

Bevor Sie API-Aufrufe tätigen können, müssen Sie sich authentifizieren. Zendesk bietet zwei Hauptmethoden an: API-Token und OAuth 2.0.

API-Token-Authentifizierung (empfohlen für serverseitige Skripte)

API-Token sind der einfachste Weg, um loszulegen. Sie generieren sie in Ihrem Zendesk Admin Center unter Apps und Integrationen > APIs > Zendesk API.

So sieht es in der Praxis aus:

curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
  -u jdoe@example.com/token:6wiIBWbGkBMo1mRDMuVwkw1EPsNkeUj95PIz2akv

Das -u Flag in cURL übernimmt automatisch die Base64-Codierung für Sie. Wenn Sie den Header manuell im Code erstellen, kombinieren Sie Ihre E-Mail und Ihr Token mit einem Doppelpunkt, Base64-codieren Sie das Ergebnis und fügen Sie es dem Authorization-Header hinzu.

OAuth 2.0 (für benutzerorientierte Anwendungen)

Wenn Sie eine clientseitige Anwendung erstellen oder im Namen einzelner Benutzer agieren müssen, ist OAuth die bessere Wahl. Es verwendet Bearer-Token:

curl https://your-domain.zendesk.com/api/v2/help_center/articles.json \
  -H "Authorization: Bearer gErypPlm4dOVgGRvA1ZzMH5MQ3nLo8bo"

Der Hauptvorteil hierbei ist, dass OAuth CORS unterstützt, wodurch es für browserbasierte Anwendungen geeignet ist. API-Token unterstützen CORS nicht und sind auf die serverseitige Verwendung beschränkt.

Sicherheitshinweis: Alle Verbindungen müssen TLS 1.2 oder höher verwenden. Speichern Sie Ihre Token sicher und übertragen Sie sie niemals in die Versionskontrolle.

Kern-API-Endpunkte und -Operationen

Die Help Center API ist um drei Hauptinhaltstypen organisiert: Kategorien, Abschnitte und Artikel. Stellen Sie es sich als eine Hierarchie vor: Kategorien enthalten Abschnitte und Abschnitte enthalten Artikel.

Arbeiten mit Artikeln

Der Artikel-Endpunkt ist der Ort, an dem Sie die meiste Zeit verbringen werden. Hier sind die wichtigsten Operationen:

Alle Artikel auflisten:

GET /api/v2/help_center/articles.json

Dies gibt eine paginierte Liste von Artikeln zurück. Sie können die Ergebnisse mithilfe von Abfrageparametern filtern:

Einen bestimmten Artikel abrufen:

GET /api/v2/help_center/articles/{article_id}.json

Einen Artikel erstellen:

POST /api/v2/help_center/sections/{section_id}/articles.json

Erforderliche Felder sind title, locale und permission_group_id. Sie können auch optionale Felder wie body (HTML-Inhalt), author_id, label_names und draft-Status festlegen.

Einen Artikel aktualisieren:

PUT /api/v2/help_center/articles/{article_id}.json

Einen Artikel archivieren:

DELETE /api/v2/help_center/articles/{article_id}.json

Endpunkte der Inhaltshierarchie

Sideloading verwandter Daten

Eine nützliche Funktion ist das Sideloading, mit dem Sie verwandte Daten in eine einzige Anfrage einbeziehen können. Fügen Sie ?include=users,sections,categories zu Ihrer Artikelanfrage hinzu, und die Antwort enthält vollständige Objekte für Autoren, Abschnitte und Kategorien anstelle von nur IDs.

Effiziente Handhabung der Paginierung

Die Paginierung ist der Punkt, an dem viele Entwickler auf ihr erstes Problem stoßen. Die Help Center API unterstützt zwei Paginierungsmethoden, und die Wahl der richtigen Methode ist wichtig.

Cursor-basierte Paginierung (empfohlen)

Die Cursor-Paginierung ist der moderne Ansatz und funktioniert bei großen Datensätzen deutlich besser. Um sie zu verwenden, fügen Sie page[size] zu Ihrer Anfrage hinzu:

GET /api/v2/help_center/articles.json?page[size]=100

Die Antwort enthält ein meta-Objekt mit einem has_more-Booleschen Wert und ein links-Objekt mit next- und prev-URLs:

{
  "articles": [...],
  "meta": {
    "has_more": true
  },
  "links": {
    "next": "https://.../articles.json?page[size]=100&page[after]=xxx",
    "prev": null
  }
}

Folgen Sie der next-URL, bis has_more falsch ist. Hier ist ein Python-Beispiel:

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-basierte Paginierung (Legacy)

Die Offset-Paginierung funktioniert immer noch, hat aber Einschränkungen. Seit August 2023 können Sie mit dieser Methode nicht mehr als 10.000 Datensätze (100 Seiten) abrufen. Wenn Sie dies versuchen, erhalten Sie einen 400 Bad Request-Fehler.

GET /api/v2/help_center/articles.json?per_page=100&page=2

Die Antwort enthält next_page- und previous_page-URLs. Stoppen Sie, wenn next_page null ist.

Fazit: Verwenden Sie die Cursor-Paginierung für neue Integrationen. Sie ist schneller, zuverlässiger und hat keine festen Grenzen.

Häufige Integrationsmuster

Nachdem Sie die Grundlagen verstanden haben, wollen wir uns ansehen, wie Entwickler diese API typischerweise in der Produktion verwenden.

Externe Suchindizierung

Ein häufiger Anwendungsfall ist die Indizierung Ihrer Zendesk-Artikel in einer externen Suchmaschine wie Elasticsearch oder Algolia. Das Muster sieht wie folgt aus:

1. Alle Artikel mithilfe der Cursor-Paginierung abrufen
2. Den HTML-Text in Klartext umwandeln (Tags entfernen)
3. Die Artikel-ID, den Titel, den Textkörper und die URL indizieren
4. Eine periodische Synchronisierung mithilfe des Parameters start_time für inkrementelle Aktualisierungen einrichten

Der Schlüssel liegt darin, die ursprüngliche Artikel-URL in Ihrem Index beizubehalten, damit Suchergebnisse zurück zu Zendesk verlinken können.

Inhaltssicherung und -migration

Für Backup-Workflows möchten Sie möglicherweise Ihre gesamte Wissensdatenbank exportieren:

1. Alle Kategorien durchlaufen
2. Für jede Kategorie die zugehörigen Abschnitte abrufen
3. Für jeden Abschnitt die zugehörigen Artikel abrufen
4. Die vollständigen Artikelobjekte (einschließlich HTML-Text) in Ihrem Backup-Speicher speichern

Dies bewahrt Ihre Inhaltshierarchie und macht die Wiederherstellung unkompliziert.

KI- und RAG-Systemintegration

Ein wachsender Anwendungsfall ist das Einspeisen von Zendesk-Inhalten in Retrieval-Augmented Generation (RAG)-Systeme für KI-gestützten Support. Der Workflow umfasst typischerweise:

1. Artikel über die API extrahieren
2. HTML in Markdown oder Klartext konvertieren
3. Den Inhalt für die Vektorspeicherung in Blöcke aufteilen
4. Die ursprüngliche URL für Zitate beibehalten

Hier können Tools wie eesel AI helfen. Anstatt benutzerdefinierte ETL-Pipelines zu erstellen, können Sie Ihr Zendesk-Konto direkt verbinden und einen KI-Agenten erhalten, der Fragen mithilfe Ihrer Wissensdatenbankinhalte beantwortet, komplett mit Zitaten zu den Originalartikeln.

Ratenbegrenzungen und Best Practices

Das Verständnis der Ratenbegrenzungen verhindert, dass Ihre Integration in großem Umfang an Grenzen stößt.

Anfragelimits nach Plan

Quelle: Zendesk Rate Limits Documentation

Umgang mit Ratenbegrenzungsfehlern

Wenn Sie das Limit überschreiten, gibt die API einen 429-Statuscode mit einem Retry-After-Header zurück, der angibt, wie viele Sekunden Sie warten müssen. Ihr Code sollte:

1. Auf 429-Antworten prüfen
2. Den Retry-After-Wert extrahieren
3. So viele Sekunden warten, bevor Sie es erneut versuchen
4. Erwägen Sie die Implementierung eines exponentiellen Backoff für wiederholte Fehler

Hier ist ein einfacher Wiederholungs-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-Tipps

• Cursor-Paginierung verwenden - sie ist schneller und hat kein Limit von 10.000 Datensätzen
• Sideloading aktivieren - Verwandte Daten in einer Anfrage abrufen, anstatt mehrere Aufrufe zu tätigen
• Aggressiv zwischenspeichern - Artikelinhalte ändern sich nicht so häufig
• Inkrementelle Exporte verwenden - Mit dem Parameter start_time können Sie nur geänderte Inhalte abrufen

Alternative Ansätze, die Sie in Betracht ziehen sollten

Das Erstellen einer benutzerdefinierten API-Integration ist nicht immer die richtige Wahl. Hier ist ein kurzer Rahmen für die Entscheidung:

Verwenden Sie die API direkt, wenn:

• Sie die vollständige Kontrolle über die Datentransformation benötigen
• Sie über dedizierte Engineering-Ressourcen verfügen
• Ihr Anwendungsfall einzigartig oder komplex ist

Verwenden Sie die nativen Funktionen von Zendesk, wenn:

• Sie nur externe Inhalte in der Suche anzeigen möchten - verwenden Sie die föderierte Suche
• Sie eine grundlegende Inhaltsverwaltung benötigen - verwenden Sie die integrierte Benutzeroberfläche

Verwenden Sie eine Integrationsplattform, wenn:

• Sie KI-gestützte Antworten ohne Erstellung von RAG-Pipelines wünschen
• Sie eine schnelle Einrichtung ohne Engineering-Ressourcen benötigen
• Sie eine kontinuierliche Synchronisierung ohne Wartungsaufwand wünschen

Hier passt eesel AI ins Bild. Anstatt benutzerdefinierte Skripte zum Extrahieren, Transformieren und Synchronisieren Ihrer Zendesk-Inhalte zu schreiben, können Sie Ihr Konto in wenigen Minuten verbinden und einen KI-Teamkollegen erhalten, der Kundenfragen mithilfe Ihrer Wissensdatenbank beantwortet. Es übernimmt die API-Integration, die Inhaltsindizierung und die Antwortgenerierung, sodass Sie sich auf höherwertige Aufgaben konzentrieren können.

Erstellen Sie leistungsstarke Wissensintegrationen mit Zendesk

Die Zendesk Help Center API bietet Ihnen die Bausteine, um ausgefeilte Wissensmanagement-Workflows zu erstellen. Egal, ob Sie einen benutzerdefinierten Suchindex erstellen, Inhalte zwischen Systemen migrieren oder Artikel in KI-Plattformen einspeisen, das Verständnis von Authentifizierung, Paginierung und Ratenbegrenzungen bereitet Sie auf den Erfolg vor.

Beginnen Sie klein: Rufen Sie eine Liste von Artikeln ab, experimentieren Sie mit der Paginierung und bauen Sie dann komplexere Integrationen auf. Und wenn Sie feststellen, dass Sie mehr Zeit mit der Wartung von Datenpipelines verbringen als mit der Lösung von Geschäftsproblemen, sollten Sie überlegen, ob eine Integrationsplattform besser geeignet ist.

Wenn Sie Ihr Zendesk-Setup mit KI-Funktionen erweitern möchten, bietet eesel AI eine direkte Integration, die Ihre Wissensdatenbank in einen intelligenten Support-Agenten verwandelt. Keine benutzerdefinierte API-Entwicklung erforderlich.