Content API: Inhalte abrufen und schreiben
Referenz der Content API von Sites: Basis-URL, Anmeldung mit Token, Umgebungen, alle Endpunkte, Filter, Beziehungen, Seiten mit Blöcken, Vorschau, Zwischenspeichern, Limits und Fehlercodes.
Basis-URL
Jede Organisation hat ihre eigene Content API:
https://<ihre-organisation>.scorebase.ch/headless/api/v1
Alle Pfade unten hängen an dieser Adresse. In den Vorlagen steht sie als HCMS_URL (dort genügt …/headless; …/headless/api/v1 wird ebenfalls akzeptiert).
Die vollständige, aus Ihren Collections erzeugte Referenz finden Sie in Sites unter API-Doku, maschinenlesbar unter /openapi.json. Siehe API-Doku, API testen und KI-Zugang.
Anmeldung
Jede Anfrage trägt ein API-Token in der Kopfzeile:
Authorization: Bearer hcms_live_ab12cd34.0123456789abcdef0123456789abcdef
| Berechtigung | Erlaubt |
|---|---|
Lesen (read) |
Alle lesenden Endpunkte |
Schreiben (write) |
Einträge anlegen, ändern, löschen |
Veröffentlichen (publish) |
Einträge mit Status published anlegen oder darauf setzen |
Vorschau (preview) |
Entwürfe und Versionen lesen, Vorschau-Links prüfen; Entwurfsseiten und Entwürfe per id nur mit ausdrücklichem ?preview=1 (siehe unten) |
Verwaltung (manage) |
Die Management-API |
Ein Token kann auf Collections und eine Umgebung beschränkt sein. Tokens erstellen Sie in Sites unter API-Tokens, siehe API-Tokens und erlaubte Herkünfte.
Öffentliche Aufrufe aus dem Browser: Formulare, Zählung und Ticketing nehmen statt der Kopfzeile auch den öffentlichen Präfix des Tokens an: ?site=hcms_live_ab12cd34. Das Token braucht dafür Lesen; schreibende Aufrufe (Formular absenden, Zählung, Reservierung, Kauf) funktionieren nur, wenn beim Token erlaubte Herkünfte eingetragen sind. Inhalte (Collections, Seiten, Menüs) lassen sich über ?site= nicht abrufen.
Ein Token gehört nie in Browser-Code. Rufen Sie die Content API aus Server-Komponenten, Serverrouten oder Build-Schritten auf.
Umgebungen
Jeder Endpunkt nimmt ?environment=<key> an. Ohne Angabe gilt die Standard-Umgebung Ihrer Organisation. Ist das Token an eine Umgebung gebunden, gilt immer diese, und der Parameter wird ignoriert. Unbekannte Keys ergeben 404 UNKNOWN_ENVIRONMENT.
Endpunkte
Collections und Einträge
| Methode | Pfad | Zweck | Berechtigung |
|---|---|---|---|
| GET | /collections |
Collections mit API aktiv; ?include=fields liefert die Felddefinitionen |
Lesen |
| GET | /collections/{slug}/entries |
Einträge einer Collection (Parameter unten) | Lesen |
| GET | /collections/{slug}/entries/count |
Anzahl, mit denselben Filtern wie die Liste | Lesen |
| GET | /collections/{slug}/entries/{id} |
Ein Eintrag | Lesen |
| POST | /collections/{slug}/entries |
Eintrag anlegen: { data, locale?, slug?, status? } (Standard: de, draft) |
Schreiben, für published auch Veröffentlichen |
| PUT | /collections/{slug}/entries/{id} |
Eintrag ändern | Schreiben, für published auch Veröffentlichen |
| DELETE | /collections/{slug}/entries/{id} |
Eintrag löschen (Papierkorb) | Schreiben |
| POST | /collections/{slug}/entries/bulk |
Bis zu 100 Operationen create, update, upsert, delete, publish, unpublish in einem Aufruf; Fehler einzelner Operationen brechen die anderen nicht ab |
Schreiben, teils Veröffentlichen |
| GET | /collections/{slug}/entries/{id}/revisions |
Versionen eines Eintrags (?include=data mit Inhalt) |
Lesen und Vorschau |
| GET | /collections/{slug}/entries/{id}/revisions/{revisionId} |
Eine Version | Lesen und Vorschau |
Seiten, Menüs, Theme und Blöcke
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /pages |
Seitenliste ohne Blöcke (?status, ?locale) |
| GET | /pages/by-path?path=/ueber-uns&locale=de |
Eine Seite mit Blöcken und SEO; fehlt die Sprache, gilt Deutsch |
| GET | /menus |
Menüs (Key und Name) |
| GET | /menus/{key} |
Ein Menü mit sichtbaren Einträgen; mit ?locale zeigen Seiten-Einträge auf die Seite in dieser Sprache |
| GET | /theme |
Tokens des Standard-Themes als { gruppe: { token: wert } } |
| GET | /blocks |
Alle verfügbaren Blöcke mit Feldern und Slots |
| GET | /redirects |
Aktive Weiterleitungen (fromPath, toPath, statusCode) |
| GET | /settings |
Tracking-Einstellungen und Ereignis-Tags, ohne Geheimnisse |
Alle mit Berechtigung Lesen.
Suche und Medien
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /search?q=… |
Volltextsuche über veröffentlichte Einträge (limit höchstens 100) |
| GET | /media |
Medienliste (page, limit höchstens 100, q) |
| GET | /media/{id}/transform?w=… |
Bild in erlaubter Grösse, ohne Token, siehe Mediathek |
Formulare und Zählung
| Methode | Pfad | Zweck | Anmeldung |
|---|---|---|---|
| GET | /forms/{key} |
Felder und Texte eines Formulars (ohne Empfängeradresse) | Token (Lesen) |
| POST | /forms/{key}/submit |
Einsendung, flaches JSON mit den Feld-Keys; Spamschutz-Feld _hp leer lassen |
Token oder ?site= |
| POST | /analytics/pageview |
Seitenaufruf { path, locale? }, Antwort 204 |
Token oder ?site= |
| POST | /analytics/event |
Ereignis { key, event?, params? }, Antwort 204 |
Token oder ?site= |
Vorschau und Dokumentation
| Methode | Pfad | Zweck |
|---|---|---|
| GET | /preview/verify?token=… |
Vorschau-Link prüfen (Token mit Vorschau) |
| GET | /preview/channel |
Live-Vorschau abfragen: gibt es einen neueren, ungespeicherten Stand? Nur Server zu Server, mit dem Kopf X-Hcms-Vorschau statt eines API-Tokens |
| POST | /preview/channel |
Meldung des Vorschaufensters weiterreichen (Auswahl, Modus, Begrüssung mit den Bausteinen der Website), höchstens 16 KB JSON |
| DELETE | /preview/channel |
Vorschau-Sitzung beenden |
| GET | /llms.txt, /llms-full.txt |
Dokumentation für KI-Werkzeuge |
| GET | /openapi.json |
OpenAPI-3.1-Beschreibung |
| POST | /graphql |
Lesende GraphQL-Schnittstelle, siehe GraphQL |
Ticketing
Tickets, Sitzplätze, Lounges und Location-Buchungen verkaufen Sie über /ticketing/…. Diese Endpunkte sind nicht in jeder Organisation freigeschaltet; die Referenz steht unter Ticketing über die Content API.
Webshop und Buchungen gehören nicht zur Content API. Katalog und Kasse liegen in der E-Commerce-App, Buchungsstrecken in der Termine-App, jeweils mit eigener Schnittstelle. Siehe Webshop und Buchungen auf der Website.
Parameter für Eintragslisten
| Parameter | Standard | Bedeutung |
|---|---|---|
status |
published |
Andere Werte (z.B. draft) nur mit Berechtigung Vorschau oder gültigem previewToken |
locale |
alle Sprachen | de, en, fr oder it |
sort |
createdAt |
createdAt, updatedAt, publishedAt, slug, status oder ein Feld-Key |
order |
desc |
asc oder desc |
page |
1 |
Seite, beginnend bei 1 |
limit |
20 |
Höchstens 100 |
populate |
– | Beziehungen auflösen, kommagetrennte Pfade, höchstens drei Ebenen tief (z.B. author,category.parent) |
fields |
– | Nur diese Felder aus data liefern |
q |
– | Volltextsuche |
filter |
– | JSON-Filter (URL-kodiert), siehe unten |
Filtern
Kurzform – je Feld ein Parameter, Operator in eckigen Klammern (ohne Klammer: gleich); mehrere werden mit UND verknüpft:
?price[gte]=10&price[lt]=100&tag[in]=a,b,c
Operatoren: eq, neq, gt, gte, lt, lte, contains, startsWith, in.
JSON-Filter (filter=, URL-kodiert) mit $eq, $ne, $gt, $gte, $lt, $lte, $contains, $startsWith, $in, $notIn, $null und Gruppen mit $and und $or (höchstens drei Ebenen, höchstens 50 Bedingungen):
{ "$or": [ { "featured": { "$eq": true } }, { "price": { "$lt": 10 } } ] }Antwortformat
Erfolg – Daten unter data, Seiteninformation unter meta:
{
"data": [ { "id": "…", "slug": "hallo", "locale": "de", "status": "published", "data": { "title": "Hallo" } } ],
"meta": { "page": 1, "limit": 20, "total": 137 }
}Fehler – immer in derselben Form:
{ "error": { "code": "FORBIDDEN", "message": "Token lacks 'read' scope" } }Werten Sie error.code aus, nicht den Text der Meldung.
Seiten mit Blöcken
GET /pages/by-path liefert den Block-Baum der Seite: je Block type (Slug), data (Feldwerte) und bei Containern children (Kind-Blöcke je Slot). Blöcke mit Verweisen auf Einträge – Feldtypen Collection, Eintrag, Abfrage und der Block collectionList – löst die Content API standardmässig auf und legt die Einträge zusätzlich unter resolved ab; data bleibt unverändert. Mit ?resolve=none erhalten Sie nur den rohen Baum. Komponenten breitet die Content API auf dem Server zu gewöhnlichen Blöcken aus (Knoten-IDs <instanz>:<knoten>); mit ?components=raw bleiben die Instanzen erhalten (type: componentInstance, mit component und translations). Öffentliche Abfragen sehen nur veröffentlichte Komponenten. Die Schemas zum Bearbeiten von Komponenten und Blöcken als Code liefert GET /editor-schemas. Die aufgelösten Collections stehen unter meta.collectionTags, praktisch für gezieltes Neuladen.
Bild-, Datei- und Galeriefelder in Blöcken enthalten in data immer eine fertige Adresse, auch wenn die Seite das Medium über seine ID kennt. Verwenden Sie die Adresse direkt. Daneben liegt das Medium als <feld>__media mit id, url, alt, title, width, height, dem Fokuspunkt (focalX, focalY) und den variants; bei Galerien ist es eine Liste in der Reihenfolge der Bilder. Den Alternativtext nehmen Sie aus dem Medium (alt). Mit ?resolve=none bleibt die Adresse, __media fehlt. Ein gelöschtes Medium ergibt eine leere Adresse und fällt aus Galerien heraus. Die Management-API liefert dagegen die gespeicherte Form mit den Medien-IDs.
Nur veröffentlichte, sichtbare Seiten werden ausgeliefert. Wie Blöcke dargestellt werden, beschreibt Eigene Blöcke bauen.
Vorschau von Entwürfen
- In Sites führt Vorschau auf die Vorschau-URL der Umgebung, ergänzt um einen Link-Token. Ein Seiten-Link gilt höchstens zwei Minuten und nur einmal, ein Eintrags-Link gilt vier Stunden.
- Ihre Website prüft ihn mit
GET /preview/verify?token=…(Token mit Berechtigung Vorschau). Bei einem Seiten-Link enthält die AntwortcookieToken, einen Sitzungs-Token für höchstens vier Stunden. Legen Sie ihn in ein Cookie, nie in eine Adresse. - Danach lädt sie den Inhalt mit
?previewToken=…. Ein Sitzungs-Token gibt die Entwürfe aller Seiten der Umgebung frei, ein Eintrags-Link genau diesen Eintrag. Solche Antworten werden nie zwischengespeichert.
Berechtigung Vorschau nur mit ausdrücklichem Signal: Ein Token mit der Berechtigung Vorschau liefert Entwurfsseiten, unsichtbare Seiten und Entwürfe per id nur, wenn die Anfrage ?preview=1 oder den Kopf X-Hcms-Preview: 1 trägt. Ohne dieses Signal verhält es sich wie ein Lese-Token. So sieht kein Besucher Entwürfe, auch wenn Ihre Website mit einem einzigen Token rendert, das die Berechtigung Vorschau trägt (die braucht /preview/verify). Senden Sie das Signal nur im Entwurfsmodus Ihrer Website. Listen mit ausdrücklichem ?status=draft brauchen es nicht.
Die Vorlagen enthalten dafür die Route /api/draft.
Live-Vorschau: Das Vorschaufenster fragt nie die Content API direkt, sondern eine Route Ihrer Website (in den Vorlagen /api/vorschau/kanal). Diese liest den Sitzungs-Token aus dem Cookie und ruft /preview/channel Server zu Server auf, mit dem Kopf X-Hcms-Vorschau. Der Endpunkt braucht kein API-Token, zählt nicht als API-Aufruf und erlaubt keine Aufrufe aus dem Browser. Eine POST-Meldung des Fensters reicht Ihre Route nur weiter, wenn sie von Ihrer eigenen Website kommt (Kopf Origin), JSON ist und höchstens 16 KB gross. Antworten: 200 mit dem Stand, 401 bei abgelaufener Sitzung, 429 mit naechsteAbfrageMs, wenn zu oft abgefragt wird. Das SDK baut die Route mit einer Zeile (vorschauKanalRoute).
Zwischenspeichern
- Veröffentlichte Inhalte kommen mit
Cache-Control: public, max-age=0, s-maxage=60, stale-while-revalidate=300und einemETag. Senden SieIf-None-Match, erhalten Sie bei unverändertem Inhalt304. - Entwürfe, Vorschau und Management-Antworten sind
no-store. - Für sofortige Aktualisierung Ihrer Website richten Sie einen Webhook ein, siehe Webhooks.
Limits
| Was | Limit |
|---|---|
| Anfragen je Token ohne eigenes Limit | 600 pro Minute (eigener Wert beim Erstellen des Tokens möglich) |
Öffentliche Aufrufe mit ?site= |
Je Besucher-IP und Minute begrenzt, schreibende strenger als lesende |
| Formular-Einsendungen | 20 pro Minute je Website und Besucher-IP |
| Bild-Transformation | 60 pro Minute je IP |
limit in Listen |
höchstens 100 |
Bei Überschreitung antwortet die Content API mit 429 und der Kopfzeile Retry-After (Sekunden).
Fehlercodes
| Status | Code | Auslöser |
|---|---|---|
| 400 | BAD_REQUEST |
Ungültiger Parameter, populate zu tief, unbekanntes Filterfeld, ungültiges JSON |
| 401 | UNAUTHORIZED |
Kopfzeile fehlt, Token ungültig oder unbekannter ?site=-Präfix |
| 401 | TOKEN_INACTIVE |
Token widerrufen |
| 401 | TOKEN_EXPIRED |
Token abgelaufen |
| 403 | FORBIDDEN |
Berechtigung fehlt |
| 403 | ORIGIN_NOT_ALLOWED |
Aufruf mit ?site= von einer nicht erlaubten Herkunft, oder schreibender Aufruf ohne eingetragene Herkünfte |
| 404 | NOT_FOUND |
Collection, Eintrag, Seite oder Menü nicht gefunden – auch, wenn die Collection nicht im Token erlaubt oder API aktiv aus ist |
| 404 | UNKNOWN_ENVIRONMENT |
Unbekannter Wert in ?environment= |
| 409 | SINGLE_ENTRY_EXISTS |
Neuer Eintrag in einer Collection der Art Einzeleintrag, die schon einen hat (im Bulk-Endpunkt als Fehler des einzelnen Postens) |
| 422 | VALIDATION_ERROR |
Ungültige Daten, z.B. bei einer Formular-Einsendung oder einem Eintrag |
| 429 | RATE_LIMIT_EXCEEDED |
Limit überschritten, siehe Retry-After |
| 500 | INTERNAL_ERROR |
Fehler bei Scorebase |
Leere Liste ohne Fehler? Standardmässig kommen nur veröffentlichte Einträge. Prüfen Sie status, locale, Filter und die Umgebung des Tokens.
Minimales Beispiel
const BASIS = process.env.HCMS_URL // …/headless/api/v1
export async function cmsFetch<T>(pfad: string): Promise<T> {
const antwort = await fetch(`${BASIS}${pfad}`, {
headers: { Authorization: `Bearer ${process.env.HCMS_TOKEN}` },
})
if (!antwort.ok) {
const body = await antwort.json().catch(() => null)
throw new Error(body?.error?.code ?? `Fehler ${antwort.status}`)
}
return antwort.json() as Promise<T>
}
const { data } = await cmsFetch<{ data: unknown[] }>("/collections/blog/entries?limit=10")In den Vorlagen übernimmt cms/client.ts diese Aufgabe, mit Typen aus cms/types.generated.ts.