SEITE

API-Dokumentation

Diese Seite besteht aus zwei Teilen: öffentlich lesbare Adressen (kein Schlüssel erforderlich, Suchmaschinen und KI-Retriever lesen direkt) und dem Skill-Kanal zur Anbindung von KI-Agenten (erfordert ein Site-Token, damit Agenten wie WorkBuddy diese Site lesen und schreiben können).

1. Öffentliche Adressen: kein Schlüssel erforderlich

AdresseZweckParameterGetesteter Status
/sitemap.xmlIndex aller öffentlichen Seiten der Sitekeine200
/robots.txtErläuterung der Crawling-Regelnkeine200
/llms.txtSite-Beschreibung und Verzeichnis öffentlicher Adressen für KI-Retrieverkeine200
/api/geo/v1/capabilitiesDeklariert die lesbaren Felder und die Liste öffentlicher Adressen dieser Sitekeine200
/capi/geo/listListet öffentliche Inhalte auf (Produkte / Kategorien / Seiten / Artikel)type, page, pageSize, updated_since200
/capi/geo/product/infoÖffentliche Wissensansicht eines einzelnen Produktshandle200
/capi/geo/entity/infoÖffentliche Ansicht von Entitätswissen wie Seitenentity_type, entity_id200

Einheitliche Rückgabe { code, message, data }, code 200 bedeutet Erfolg. Es werden nur bereits veröffentlichte Inhalte zurückgegeben: freigeschaltete Produkte, veröffentlichte Seiten und Artikel.

2. Anbindung von KI-Agenten (Skill-Kanal)

Kurz gesagt: Schnittstellenadresse + Site-Token, beide Werte im Agenten eintragen und er ist einsatzbereit. Das Token entspricht den Backend-Berechtigungen dieser Site; es gehört ausschließlich in den Request-Header, nicht in die URL und nicht ins Code-Repository.

1. Beide Werte abrufen

  1. Im Backend anmelden und in der linken Navigation die Seite „KI-Verbindung“ öffnen.
  2. Auf der Seite stehen zwei Zeilen: Schnittstellenadresse (diese Site fest auf /api/skill, vollständige Adresse https://deine-domain/api/skill) und Zugriffstoken (beginnt mit sk_).
  3. Rechts auf die Kopierschaltfläche klicken; alternativ „Anbindungsanleitung kopieren“ anklicken, um Adresse, Authentifizierung und Schnittstellenerkennung in einem Block an den Agenten zu übergeben.

Ein Zurücksetzen des Tokens macht das alte Token sofort ungültig; bereits verwendende Agenten müssen synchron aktualisiert werden, sonst geben alle Aufrufe 401 zurück.

2. Authentifizierung

Alle Skill-Schnittstellen akzeptieren nur einen Request-Header: X-Site-Token: dein Token. Das Token kann nicht als URL-Parameter übergeben werden – URLs landen in Zugriffsprotokollen, Referern und Browserverläufen und würden die Backend-Berechtigungen offenlegen.

Ein minimaler Aufruf (Domain und Token durch eigene ersetzen):

curl -s https://deine-domain/api/skill/capabilities \
-H "X-Site-Token: sk_dein_token"

3. Erst fragen „Was kannst du?“, dann konkrete Schnittstellen aufrufen

Nicht zu Beginn Schnittstellennamen raten. Zwei Self-Service-Schnittstellen sind immer verfügbar; der Agent entdeckt seine Fähigkeiten selbst darüber:

  • GET /api/skill/capabilities —— vollständige Fähigkeitsliste: Schnittstellenpfade, Methoden, Lese-/Schreibtyp, Parameterbeschreibungen sowie Authentifizierungsart und Versionsnummer dieser Site.
  • GET /api/skill/base/init —— Basisinformationen der Site: Site-Typ (B2B / B2C), aktuelles Theme, verfügbare Themes, Sprachen und Währungen.

Die übrigen Schnittstellen sind nach Modulen gegliedert, häufig genutzt: /api/skill/product/list (Produkte), /api/skill/plugin/list (Plugins), /api/skill/i18n/list (mehrsprachige Einträge), /api/skill/analytics/traffic-get (Traffic), /api/skill/b2c-order/list (Bestellungen, B2C-Site).

4. Berechtigungsmatrix: standardmäßig alles offen, pro Modul einschränkbar

Im Backend unter „Schnittstellenberechtigungen“ gibt es zwei Stufen: alles erlauben (Standard, entspricht dem Verhalten bei Freischaltung) und nach Modul einschränken (Lese- / Schreib- / riskante Operationen pro Modul einzeln schaltbar).

KategorieBedeutungEmpfehlung
Nur LesenProdukte, Inhalte, Traffic, Plugin-Status abfragenstandardmäßig aktiviert
SchreibenProdukte, Inhalte, Layouts anlegen oder ändernaktivieren, wenn der Agent stellvertretend operiert
RiskantLöschen, siteweites Überschreiben, Veröffentlichungsvorgängenur bei eindeutigem Bedarf aktivieren

Die beiden Nur-Lese-Schnittstellen „Schnittstellenliste (capabilities)“ und „Site-Initialisierung (base/init)“ sind immer freigegeben und von der Berechtigungstabelle unabhängig – sonst könnte der Agent nicht einmal nachvollziehen, „warum keine Verbindung möglich ist“. Änderungen gelten sofort nach dem Speichern; auf Agentenseite ist keine Konfigurationsänderung nötig. Gesperrte Schnittstellen geben 403 zurück und nennen den Grund.

5. Testprotokoll (2026-10-19, je einmal auf zwei Kundensites getestet)

Mit dem jeweiligen echten Token jeder Site einzeln aufgerufen, Ergebnisse wie folgt (unbearbeitet, exakt die damaligen Rückgaben):

SchnittstelleB2B-SiteB2C-Site
GET /api/skill/capabilities200 / 46.063 B200 / 45.842 B
GET /api/skill/base/init200 / 644 B200 / 664 B
GET /api/skill/product/list?limit=2200 / 25.534 B200 / 5.417 B
GET /api/skill/analytics/traffic-get200 / 3.424 B200 / 2.913 B
GET /api/skill/plugin/list200 / 15.673 B200 / 14.681 B
GET /api/skill/i18n/list200 / 5.275 B200 / 5.275 B
wie oben, jedoch ohne Token401 / 68 B401 / 68 B

Fazit: Der Zugang beider Sites funktioniert, die Authentifizierung greift, ohne Token wird beides abgelehnt (Rückgabe „Nicht autorisiert: X-Site-Token fehlt oder stimmt nicht überein“). Unterschiedliche Größen sind Datenmengenunterschiede, keine Störung.

6. Fehlercodes und Behandlung

StatusBedeutungVorgehen
401Token fehlt oder stimmt nicht übereinPrüfen, ob der Header-Name X-Site-Token lautet; ob das Token zurückgesetzt wurde
403Von der Berechtigungsmatrix blockiertreason in der Rückgabe prüfen; im Backend unter „Schnittstellenberechtigungen“ das entsprechende Modul freigeben
404Pfad existiert nichtZunächst mit capabilities den Schnittstellennamen abgleichen, nicht aus dem Gedächtnis zusammensetzen
503Serverseitig kein Site-Token konfiguriertDie Seite „KI-Verbindung“ im Backend einmal normal öffnen, das System generiert es automatisch

7. Drei Sicherheitsgrundregeln

  1. Token nicht in die URL, auch nicht in Chatfenster einfügen oder ins Code-Repository committen – es entspricht dem Backend-Login-Status.
  2. Nur notwendige Berechtigungen vergeben: für den täglichen Betrieb reichen Nur-Lesen + Schreiben, riskante Kategorien nur bei Bedarf temporär aktivieren.
  3. Bei Personenwechsel oder Übergabe das Token zurücksetzen, das alte Token wird sofort ungültig – zuverlässiger als einzelnes Widerrufen.

3. Minimale Schritte zur Anbindung von WorkBuddy

  1. Backend „KI-Verbindung“ → Schnittstellenadresse und Zugriffstoken kopieren (oder direkt die gesamte Anbindungsanleitung kopieren).
  2. In der Konnektor- / Skill-Konfiguration von WorkBuddy die Site-Adresse eintragen, Authentifizierung über X-Site-Token.
  3. Den Agenten zuerst capabilities zur Selbstbeschreibung aufrufen lassen, dann gemäß Liste die konkreten Schnittstellen aufrufen.