# CMS per API steuern: Arbeitsabläufe für Maschinen > So pflegen Skripte, Workflows und Agenten eine CMF-Website per API: Zugang einrichten, typische Abläufe, n8n, Fehlerauswertung und die wichtigsten Fallen. Kanonische URL: https://cmf.brosemedien.de/maschinen-anleitung --- # Maschinen-Anleitung: Arbeitsabläufe mit der API Wie Skripte, Workflows und Agenten eine CMF-Website pflegen – vom eigenen Zugang über typische Abläufe bis zu den Fallen, an denen Automatisierungen scheitern. Alle 30 Aktionen mit Aufbau und Antworten stehen in der [API-Referenz](/api-anleitung). ### Inhalt - [Vorbereitung](#vorbereitung) - [Maschine einrichten](#maschinen-einrichten) - [Szenarien](#szenarien) - [Automatisierung mit n8n](#n8n) - [Fallen und Fehlerauswertung](#fallen) - [Grenzen der API](#grenzen) - [Tipps](#tipps) - [Live-Beispiel: diese Website](#live-beispiel) ### Worum geht es? CMF hat eine JSON-API. Jede Maschine, die HTTP-Anfragen senden kann – Claude Code, ein n8n-Workflow, ein Custom GPT mit Actions oder ein eigenes Skript –, kann damit Seiten, Blog-Beiträge, Medien und das Design lesen und ändern. Diese Website wird selbst so gepflegt: Die News-Beiträge vom 15.09.2026 wurden komplett per API angelegt. ## 1. Vorbereitung ### Eigenen API-Zugang anlegen Im Admin unter **Benutzer** → „Neuen Zugang anlegen“: Benutzername und Passwort eingeben, das Häkchen „API-Zugang anlegen“ setzen, „Benutzer anlegen“. Das Token (`cms_…`) wird **genau einmal** angezeigt – sofort kopieren. Gespeichert wird nur ein Hash. Leg für jeden Agenten und jeden Workflow einen eigenen Zugang an. Dann kannst du einen einzelnen löschen, ohne die anderen zu stören. Beachte: Jeder API-Benutzer ist zugleich voller Admin. Schritt für Schritt: [Installationsanleitung](/installationsanleitung#api-zugang). ### README_MASCHINEN.md als Kontext Die Kurzreferenz [README_MASCHINEN.md](/files/README_MASCHINEN.md) liegt jedem Download bei. So nutzt du sie: - Datei herunterladen - Oben die API-Basis auf deine Domain ändern (z. B. `https://meine-domain.de/api.php`) - Dem Agenten als Kontextdatei oder System-Prompt mitgeben - Das Token getrennt übergeben, etwa als Umgebungsvariable Trag das Token nie in die Datei auf dem Server ein – `/files/` ist öffentlich. Vollständige Details: [API-Referenz](/api-anleitung). ### Verbindung testen Bevor die Maschine loslegt, prüfst du die Verbindung: ``` GET /api.php?a=site_bundle Authorization: Bearer cms_… ``` Die Antwort beginnt mit `{"ok": true, "data": {…}}` und enthält `site`, `styles`, `header`, `footer` und `custom_css`. Kommt `401` mit `missing_token`, reicht der Server den Authorization-Header womöglich nicht durch – dann das Token im Header `X-API-Token` senden. Bei `invalid_token` stimmt das Token nicht. ## 2. Maschine einrichten ### Claude Code und andere Coding-Agenten Die README_MASCHINEN.md in den Projektordner legen oder in der `CLAUDE.md` darauf verweisen, das Token als Umgebungsvariable bereitstellen. Claude Code schickt die HTTP-Anfragen dann selbst, zum Beispiel per `curl` oder mit einem kleinen Node.js-Skript. **Beispiel-Anweisung:** *„Lies die README_MASCHINEN.md und lege auf meiner CMF-Website eine Seite ‚Über uns‘ als Entwurf an. Nutze die API und zeig mir danach den Slug aus der Antwort.“* ### Assistenten mit HTTP-Aufrufen Ein KI-Assistent kann deine Website nur ändern, wenn er selbst HTTP-Anfragen senden darf. Das können zum Beispiel Claude Code, ein Custom GPT mit Actions oder ein n8n-Workflow mit KI-Knoten. Für einen Custom GPT beschreibst du die benötigten Aktionen selbst als Action-Schema – CMF liefert dafür keine fertige Vorlage mit. Ein Chat ohne solche Werkzeuge kann das JSON nur vorbereiten. Abschicken musst du es dann selbst. ### n8n und andere Workflow-Tools Mit n8n oder ähnlichen Werkzeugen läuft der ganze Ablauf ohne dich: - Auslöser (Zeitplan, Webhook, E-Mail) - Ein KI-Knoten erzeugt den Inhalt als JSON - Ein HTTP-Knoten schickt ihn an die CMF-API Praktisch für n8n: `content` darf bei `page_create`, `page_update` und `partial_update` auch als JSON-Text statt als Objekt ankommen. ## 3. Szenarien Jedes Szenario zeigt, was du der Maschine sagst und welche Aktionen sie nutzt. Aufbau der Anfragen und Antworten: [API-Referenz](/api-anleitung). ### Komplette Website erstellen **Anweisung an die Maschine:** *„Erstelle eine Website für eine Fotografin: Startseite, Über mich, Portfolio, Kontakt. Nutze die CMF-API, lade keine Bilder hoch und setze passende Farben im Theme.“* **Was die Maschine tut:** - `site_bundle` lesen – aktuellen Stand verstehen - `styles_update` – Farben und Schriften setzen (ein Teilobjekt reicht) - `page_create` je Seite, mit `nav` – sonst erscheint jede veröffentlichte Seite automatisch im Menü - Den `slug` aus jeder Antwort übernehmen, bevor Links gesetzt werden - `partial_update` für Header und Footer – ersetzt den Bereich komplett **Tipp:** Zielgruppe, Tonalität und gewünschte Struktur angeben. Je konkreter die Anweisung, desto besser das Ergebnis. ### Website klonen oder umziehen Für einen vollständigen Umzug nimmst du den **Admin, nicht die API**: - Quelle: *Einstellungen* → Export, alle Häkchen (Header, Footer, Seiten, Medien, Blog, Theme und Custom CSS) → „ZIP exportieren“ - Ziel: *Einstellungen* → Import → „ZIP analysieren“ → „Import starten“ - `site.json` ist nicht im ZIP: auf dem Ziel `name`, `lang` und `baseUrl` prüfen Medien behalten dabei ihre Pfade, alle Bilder in den Inhalten stimmen weiter. **Warum nicht per API?** `site_export` und `site_import` enthalten weder Blog noch Medien. Und jede per `media_upload` neu hochgeladene Datei bekommt einen neuen Zufallsanhang im Dateinamen – die Bildpfade in den übertragenen Inhalten zeigen dann ins Leere. ### Gestaltung überarbeiten **Anweisung an die Maschine:** *„Ändere das Design: Primärfarbe Dunkelblau (#1a365d), Schrift Montserrat, Container 1200px. Der Header soll Logo und Slogan zeigen.“* **Was die Maschine tut:** - `site_bundle` lesen – aktuelle Styles, Header und Custom CSS verstehen - `styles_update` – nur die geänderten Werte schicken, der Rest bleibt - `custom_css_update` – ersetzt die komplette `custom.css`: vorhandenes CSS aus `site_bundle` übernehmen, ergänzen, vollständig zurücksenden - `partial_update&part=header` – den ganzen Header zurückschreiben **Tipp:** Nach dem Theme die Inhalte ansehen – manche Layouts wirken mit anderen Farben oder Schriften anders. ### Inhalte ergänzen **Anweisung an die Maschine:** *„Füge auf der Seite ‚Leistungen‘ einen Abschnitt ‚Beratung‘ hinzu: Überschrift h2, zwei Absätze, ein Button zur Kontaktseite.“* **Was die Maschine tut:** - `page&slug=leistungen` – Seite laden, `data.page.id` und `data.content` merken - Neue Blöcke in `content.blocks` einfügen, vorhandene Blöcke und IDs unverändert lassen - `page_update&id=…` mit `{"content": …}` – das komplette Objekt samt `meta` zurückschicken **Wichtig:** `content` ersetzt das ganze Dokument. Was die Maschine weglässt – ein Block, `meta.image`, `meta.robots` –, ist danach weg. ### Blog automatisiert schreiben **Anweisung an die Maschine:** *„Schreib einen Beitrag über schnelle Websites, Kategorie wie im Blog vorhanden, mit passendem Bild aus der Mediathek, und veröffentliche ihn.“* **Was die Maschine tut:** - `blog_posts` – vorhandene Themen und `data.categories` lesen; die Kategorie exakt so übernehmen - `media` – vorhandene Bilder durchsuchen (oder `media_upload` und `src` aus der Antwort nehmen) - `blog_create` mit `title`, `slug`, `status`, `image`, `category`, `description` und `content` **Zwei Beschreibungen:** `description` erscheint auf der Karte, im Feed und in der `llms.txt`, `content.meta.description` im Meta-Tag der Beitragsseite – beide setzen. Neue Beiträge landen in der Übersicht oben. ### SEO und Meta-Daten prüfen **Anweisung an die Maschine:** *„Prüf alle Seiten: Meta-Titel und -Beschreibung verbessern, fehlende Alt-Texte ergänzen, Überschriften-Hierarchie korrigieren.“* **Was die Maschine tut:** - `pages` – alle Seiten auflisten - Jede Seite per `page&id=…` laden - Meta-Titel, Beschreibung, Alt-Texte und Überschriften prüfen - Per `page_update` mit dem vollständigen `content` zurückschreiben **Gut zu wissen:** Sitemap, Feed, `llms.txt` und Suchindex entstehen bei jeder Seiten- oder Blog-Änderung automatisch neu. `sitemap_generate` brauchst du nur nach `site_update`, etwa wenn sich die `baseUrl` ändert. ## 4. Automatisierung mit n8n ### Workflow-Aufbau Ein typischer n8n-Workflow für CMF hat vier Bausteine: - **Auslöser** – Zeitplan (z. B. jeden Montag), Webhook oder manuell - **KI-Knoten** – Claude, GPT oder ein lokales Modell erzeugt den Inhalt als JSON - **HTTP-Knoten** – schickt das Ergebnis an die CMF-API (`page_create`, `blog_create` oder `page_update`) - **Prüfung** – ein IF-Knoten wertet `ok` und die zurückgegebenen Daten aus **Einstellungen für den HTTP-Knoten:** - Methode: POST (Lesen: GET) - Header: `Authorization: Bearer cms_…` - Content-Type: `application/json` - Body: das erzeugte JSON – das Dokument (meta und Blöcke) steht immer im `content`-Wrapper, bei `page_create`, `blog_create`, `page_update`, `blog_update` und `partial_update` ### Beispiel: wöchentlicher Blog-Beitrag - **Schedule Trigger** – jeden Montag um 9:00 - **HTTP Request** – `GET ?a=blog_posts`, um vorhandene Themen und Kategorien zu kennen - **KI-Knoten** – Prompt: *„Schreib einen Beitrag für ein dateibasiertes CMS. Vermeide diese Themen: [Liste]. Gib title, slug, description, category und content als JSON zurück, content im CMF-Blockformat.“* - **HTTP Request** – `POST ?a=blog_create` mit dem Ergebnis als Body, `status` zunächst `draft` - **IF** – bei `ok: false` die `details` an dich melden, sonst den Link aus `data.post.slug` bauen **Tipp:** Gib dem KI-Knoten die README_MASCHINEN.md als Kontext mit, damit er das Blockformat kennt. Mit `draft` siehst du den Beitrag vor der Veröffentlichung. ## 5. Fallen und Fehlerauswertung Die meisten fehlgeschlagenen Automatisierungen scheitern nicht an einem Fehlercode, sondern an einer Antwort mit `ok: true`, die trotzdem nicht das Gewünschte bewirkt hat. Diese Punkte sollte jede Maschine kennen: ### Was ersetzt, was zusammengeführt wird - **`page_update` / `blog_update` mit `content`** ersetzen das ganze Dokument inklusive `meta`. `meta.image` und `meta.robots` also mitschicken. `meta` kennt nur `title`, `description`, `robots` und `image`, alles andere wird verworfen. - **Ohne `content`** ändert `page_update` nur Titel, Slug, Status oder `nav`, der Inhalt bleibt. - **`nav`** wird zusammengeführt: `{"nav": {"show": false}}` reicht. - **`site_update`** ersetzt `site.json` komplett (Pflicht: `name`, `lang`). Erst `site` lesen, ändern, vollständig zurücksenden. - **`custom_css_update`** ersetzt `custom.css` komplett. - **`partial_update`** ersetzt Header oder Footer komplett. - **`styles_update`** führt zusammen: ein Teilobjekt reicht. ### Antworten prüfen - **`page_create`:** `nav.show` ist standardmäßig `true` – eine veröffentlichte Seite ohne `nav` erscheint im Menü. - **Slug aus der Antwort übernehmen:** Ist er schon vergeben, hängt CMF `-2` an. Die Antwort (201) enthält den tatsächlichen Slug. - **`nav.parent`** nimmt ID oder Slug. Unbekannte Eltern, Selbstbezug oder Schleifen setzt CMF ohne Fehlermeldung auf `null` – den Wert in der Antwort prüfen. - **`site_import`** antwortet mit `ok: true`, auch wenn Teile abgelehnt wurden: `data.rejected` auswerten. - **`blocks: []`** erzeugt einen Platzhalter (Überschrift und „Inhalt hier.“). - **Grundsatz:** `ok: true` heißt nicht „Inhalt wie gewünscht“. `data.content` der Antwort mit dem Gesendeten vergleichen. Antwort Bedeutung Was die Maschine tun sollte `400` `invalid_json`, `missing_id`, `missing_path` Anfrage unvollständig oder kein gültiges JSON Body und Parameter prüfen, erneut senden `401` `missing_token`, `invalid_token`, `token_disabled` Anmeldung fehlgeschlagen Abbrechen und melden – nicht wiederholen `404` `page_not_found`, `post_not_found`, `unknown_action` ID, Slug oder Aktion gibt es nicht Liste neu lesen (`pages`, `blog_posts`), Aktionsnamen prüfen `405` `method_not_allowed` GET statt POST oder umgekehrt Methode laut Referenz verwenden `409` `media_in_use` Datei wird noch verwendet `data.references` zeigt, wo – erst dort entfernen `415` `unsupported_filetype`, `mime_mismatch` Dateityp nicht erlaubt oder Inhalt passt nicht zur Endung Datei umwandeln oder richtig benennen `422` `invalid_page_schema` u. a. Inhalt verletzt das Schema (`invalid_svg`: Datei ist kein lesbares SVG, ohne `details`) `details` lesen – dort steht der genaue Fehler, z. B. „doppelte id“ –, korrigieren, erneut senden `500` Serverfehler, oft fehlende Schreibrechte Abbrechen und den Betreiber informieren ## 6. Grenzen der API - Keine API für Formular-Einsendungen, Benutzer und Tokens, Blog-Einstellungen (URL-Prefix, Kategorien) und das System-Update – das bleibt im Admin. - site_export und site_import enthalten weder Blog noch Medien. Für einen kompletten Umzug: Admin-Export und -Import. - pages_import prüft Inhalte nicht gegen das Schema – für neue Seiten page_create verwenden. - Der html-Block wird ungefiltert ausgegeben. Eine Maschine, die html-Blöcke schreibt, schreibt direkt in die Website. - Änderungen sind sofort live und haben keine Versionsgeschichte. Neue Inhalte zunächst als draft anlegen und vor großen Änderungen einen Admin-Export ziehen. ## 7. Tipps ### Gute Prompts schreiben - README_MASCHINEN.md als Kontext mitgeben - Zielgruppe und Tonalität beschreiben - Gewünschte Seitenstruktur vorgeben - Blocktypen nennen (z. B. „columns für die Vorteile“) - Die Maschine anweisen, erst zu lesen und dann zu schreiben - Verlangen, dass sie jede Antwort prüft und Fehler meldet ### Sicherheit - Token nie in öffentliche Dateien, Repositories oder geteilte Prompts - Jeder Agent und jeder Workflow bekommt einen eigenen Zugang - Token erneuern: neuen Zugang anlegen, alten löschen - Zugänge löschen, die nicht mehr gebraucht werden - Vor großen Änderungen einen Admin-Export ziehen ### Arbeitsablauf - Erst lesen (site_bundle, page), dann ändern - Inhalte vollständig zurückschreiben, samt meta - Block-IDs unverändert lassen - Medien erst hochladen, dann src aus der Antwort einbinden - Ergebnis im Frontend oder als .md ansehen - Bei vielen Änderungen Seite für Seite arbeiten ## 8. Live-Beispiel: diese Website cmf.brosemedien.de wird selbst über die API gepflegt. Die News-Beiträge vom 15.09.2026 – etwa [CMF 1.17.0](/news/cmf-1-17-0) – sind komplett per API entstanden. Was eine Maschine von dieser Website lesen kann, siehst du hier: - [/llms.txt](/llms.txt) – der Wegweiser: alle Seiten und Beiträge mit Beschreibung und Markdown-Link - [/maschinen-anleitung.md](/maschinen-anleitung.md) – diese Seite als Markdown - [/news/cmf-1-17-0.md](/news/cmf-1-17-0.md) – ein per API angelegter Beitrag als Markdown - [/files/README_MASCHINEN.md](/files/README_MASCHINEN.md) – die Kurzreferenz für Agenten - [/sitemap.xml](/sitemap.xml) und [/feed.xml](/feed.xml) – neu geschrieben nach jeder Änderung an Seiten oder Beiträgen - [API-Referenz](/api-anleitung) - [README_MASCHINEN.md herunterladen](/files/README_MASCHINEN.md) - [Installationsanleitung](/installationsanleitung) - [Anleitung für Menschen](/humanoid-anleitung)