API-Doku, API testen und KI-Zugang
Die automatisch erzeugte Referenz Ihrer Content API nutzen, Anfragen im Browser ausprobieren und KI-Werkzeugen mit llms.txt, llms-full.txt und openapi.json das nötige Wissen geben.
Worum es geht
Die Content API Ihrer Organisation beschreibt sich selbst: Aus Ihren Collections, Blöcken, Layouts und dem Theme erzeugt Scorebase laufend eine Referenz – für Menschen in der App, für Programme als OpenAPI-Datei und für KI-Werkzeuge als Textdatei. Ändern Sie eine Collection, ist die Doku nach wenigen Minuten auf dem neuen Stand.
Die Seite „API-Doku“
Öffnen Sie API-Doku (Abschnitt Entwickler). Oben steht der Setup-Guide für Entwickler:
- Basis-URL deiner Organisation – z.B.
https://<ihre-organisation>.scorebase.ch/headless/api/v1. Alle Endpunkte hängen an dieser Adresse. - Quickstart – der Befehl, mit dem ein Website-Projekt entsteht (siehe Eigene Website anbinden).
- Token-Scopes – was die Berechtigungen Lesen (
read), Schreiben (write), Veröffentlichen (publish), Vorschau (preview) und Verwaltung (manage) erlauben. - Maschinenlesbare Doku – Links auf
llms.txt,llms-full.txtundopenapi.json. - Environments – Hinweis auf den Parameter
?environment=<key>.
Darunter folgt die interaktive Referenz aller Endpunkte, mit Ihren Collections und ihren Feldern. Dort lassen sich Anfragen mit einem eigenen Token direkt ausprobieren.
Die Seite ist für alle mit Zugang zu Inhalte sichtbar.
Die Seite „API testen“
Unter API testen (Titel API-Playground) schicken Sie einzelne Anfragen an Ihre Content API, ohne ein Werkzeug zu installieren:
- Wählen Sie unter Endpunkt einen Eintrag aus der Liste, oder tragen Sie Methode und Pfad selbst ein, z.B.
GETund/collections/blog/entries. - Optional: Query (optional), z.B.
locale=de&limit=5, und beiPOSToderPUTeinen Body (JSON). - Fügen Sie unter Bearer-Token ein vollständiges API-Token ein. Es wird nicht gespeichert; die Namen Ihrer vorhandenen Tokens stehen darunter nur zur Orientierung.
- Klicken Sie auf Senden. Unter Antwort sehen Sie Status und Inhalt.
Für API testen brauchen Sie das Recht Einstellungen verwalten.
Tipp: Testen Sie mit einem Token, das nur Lesen darf. So kann beim Ausprobieren nichts verändert werden.
Maschinenlesbare Dokumentation
| Adresse (an die Basis-URL angehängt) | Inhalt |
|---|---|
/llms.txt |
Kurzfassung für KI-Werkzeuge: Basis-URL, Anmeldung, Liste der Collections mit Feldern, wichtigste Endpunkte |
/llms-full.txt |
Vollständige Doku: Feldtabellen je Collection mit Beispielanfrage und Beispielantwort, alle Blöcke mit Feldern, Layouts, die CSS-Variablen Ihres Standard-Themes, Anleitungen (Filter, Beziehungen, Vorschau, Zwischenspeichern, Umgebungen, Formulare, Ticketing, Analytics) und eine Endpunkt-Übersicht |
/openapi.json |
OpenAPI-3.1-Beschreibung aller Endpunkte, z.B. für Code-Generatoren |
Alle drei Adressen brauchen ein Token (Kopfzeile Authorization: Bearer …, Berechtigung Lesen) und gelten für eine Umgebung (?environment=<key>, sonst die Standard-Umgebung). llms.txt und llms-full.txt nehmen das Token für schnelle Tests auch als ?token= an – vermeiden Sie das im Betrieb, weil Adressen in Protokollen und im Browserverlauf landen.
Nur Collections mit eingeschaltetem API aktiv erscheinen in der Doku. Als Beispielantwort nimmt llms-full.txt einen veröffentlichten Eintrag der Collection (lange Texte gekürzt). Bei Collections, die als Personendaten gekennzeichnet sind, erfindet Scorebase das Beispiel stattdessen – echte Personendaten erscheinen dort nie.
KI-Werkzeuge beim Bauen der Website
Ein KI-Assistent in Ihrer Entwicklungsumgebung arbeitet am besten mit einer lokalen Kopie der Doku:
npx hcms docs pull # schreibt cms/llms-full.txt
npx hcms types generate # schreibt cms/types.generated.tshcms init erledigt beides beim Anlegen des Projekts. Wiederholen Sie die Befehle nach jeder Änderung an Collections oder Blöcken. Die Vorlagen enthalten zusätzlich eine Anleitung für KI-Assistenten im Projekt. Mit hcms library list --json und cms/LIBRARY.md kennt der Assistent auch die Bausteinbibliothek (siehe Bausteinbibliothek).
Soll ein KI-Assistent nicht nur Code schreiben, sondern direkt in Ihrer Organisation Collections und Einträge anlegen, geht das über den MCP-Zugang von Scorebase. Mehr zu KI in Scorebase: KI-Funktionen.
Wenn etwas nicht klappt
| Symptom | Ursache | Lösung |
|---|---|---|
| Eine Collection fehlt in der Doku | API aktiv ist aus, oder sie liegt in einer anderen Umgebung | Schalter prüfen; ?environment= angeben |
| Die Doku zeigt einen alten Stand | Die Doku wird einige Minuten zwischengespeichert | Kurz warten, dann neu laden bzw. hcms docs pull wiederholen |
| API testen antwortet mit 401 | Token unvollständig eingefügt oder widerrufen | Vollständiges, aktives Token einfügen |
| „Du hast keine Berechtigung, den API-Playground zu nutzen.“ | Ihnen fehlt Einstellungen verwalten | Ihre Administratorin kann das Recht vergeben |