Octi Builder — API and MCP
Overview
This area exposes 61 operations. Each of them is at the same time an MCP tool.
This area is behind the module switch module.builder. With the module off, these operations answer 404.
Operations
| Method | Path | Purpose | Permission | Parameters | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
GET | /api/v1/builder/asset-folders | Ordner der Medienbibliothek — Belegte Ordner samt Anzahl, alphabetisch. Marken-Schnitt am Recht builder.page.view — sonst verriete allein die Ordner-Auswahl, welche Ordner es in fremden Marken gibt. | builder.page.view | brandId | ||||||||
GET | /api/v1/builder/asset-folders/{folder} | Read one BuilderAssetFolder | builder.page.view | folder | ||||||||
GET | /api/v1/builder/assets | Medienbibliothek durchsuchen — Bilder des Baukastens mit Ordner, Alternativtext und srcset-Varianten. Der Alternativtext am Medium ist die EINE gepflegte Fassung — der Bild-Wähler übernimmt sie in den Baustein, wo sie überschreibbar bleibt. Marken-Schnitt am Recht builder.page.view (Audit R28). | builder.page.view | page, brandId, folder, q, itemsPerPage, order[createdAt], order[originalName] | ||||||||
POST | /api/v1/builder/assets | Bild in die Medienbibliothek hochladen — Bild als Base64 in contentBase64, Dateiname in originalName; optional convertToWebp (Vorgabe an), brandId, folder, alt. Nur PNG, JPEG, WebP, GIF. Erzeugt die srcset-Varianten. Marken-Schnitt am Recht builder.page.update. | builder.page.update | + body | ||||||||
DELETE | /api/v1/builder/assets/{ulid} | Medium aus der Bibliothek nehmen — Soft-Delete des Katalog-Eintrags. Die Datei bleibt liegen — eingefrorene Releases verweisen weiter auf sie. | builder.media.manage | ulid | ||||||||
GET | /api/v1/builder/assets/{ulid} | Read one BuilderAsset | builder.page.view | ulid | ||||||||
PATCH | /api/v1/builder/assets/{ulid} | Medium pflegen — Ordner, Alternativtext und Anzeigename. Die DATEI ändert nur POST /v1/builder/assets/{ulid}/content. | builder.media.manage | ulid, + body | ||||||||
POST | /api/v1/builder/assets/{ulid}/content | Datei eines Mediums ersetzen — Neues Bild als Base64 in contentBase64, optional originalName. Die Adresse des Mediums bleibt, die srcset-Varianten werden neu erzeugt und der Zwischenspeicher der Websites entwertet — ein Logo-Wechsel wirkt so auf jeder Seite. Nur PNG, JPEG, WebP, GIF; WebP-Medien werden gewandelt, andere müssen formgleich sein. Marken-Schnitt am Recht builder.media.manage in der Marke des Mediums. | builder.media.manage | ulid, + body | ||||||||
GET | /api/v1/builder/block-types | Baustein-Palette des Editors — Alle registrierten Baustein-Typen mit settingsSchema, sortiert nach Kategorie/Label. | builder.page.view | — | ||||||||
GET | /api/v1/builder/collection-source-items | Einträge einer Listen-Quelle (für kuratierte Listen) — Auswahl-Paare {id, label} für den idIn-Eintrags-Wähler; maximal 50, nur Veröffentlichtes. | builder.page.view | source, siteUlid, pageUlid, brandId, q | ||||||||
GET | /api/v1/builder/collection-sources | Listen-Quellen des Baukastens — Je Quelle: key, label, group, Feld-Schema (fields[] mit key/label/type/island/refSource), sortableFields[] und supportsDetailUrl. island: true heißt: der Wert wird nie eingebacken, sondern live nachgeladen. | builder.page.view | siteUlid, brandId, pageUlid | ||||||||
DELETE | /api/v1/builder/comments/{ulid} | Delete a BuilderPageComment | builder.page.view | ulid | ||||||||
POST | /api/v1/builder/comments/{ulid}/resolve | Kommentar als erledigt markieren — Payload {resolved} — false öffnet den Thread wieder. Der Thread bleibt in jedem Fall lesbar. | builder.comment.resolve | ulid, + body | ||||||||
GET | /api/v1/builder/dynamic-sources | Collection of BuilderDynamicSource | builder.page.view | — | ||||||||
GET | /api/v1/builder/dynamic-sources/{key} | Read one BuilderDynamicSource | builder.page.view | key | ||||||||
GET | /api/v1/builder/fonts | Selbst gehostete Webschriften — Ein Schnitt je Zeile (Familie + Stärke + Stil). Genau daraus entstehen die @font-face-Regeln des ausgelieferten Stylesheets und der Vorlade-Hinweis im Dokumentkopf. Nur woff2 und woff; geprüft wird die DATEISIGNATUR, nicht die Endung. | builder.page.view | brandId | ||||||||
POST | /api/v1/builder/fonts | Schriftschnitt hochladen — Datei als Base64 in contentBase64 plus Familie, Stärke (100–900), Stil (normal\ | italic), font-display und Vorlade-Markierung; optional brandId. Nur woff2 und woff, geprüft an der DATEISIGNATUR. Marken-Schnitt am Recht builder.theme.manage. | builder.theme.manage | + body | |||||||
DELETE | /api/v1/builder/fonts/{ulid} | Schnitt entfernen — Soft-Delete plus Löschen der Datei: eine Schriftdatei, die niemand mehr ausliefert, soll nicht weiter öffentlich abrufbar auf dem Webspace liegen (Lizenzbedingungen von Schriften verlangen das regelmäßig). | builder.theme.manage | ulid | ||||||||
GET | /api/v1/builder/fonts/{ulid} | Read one BuilderFont | builder.page.view | ulid | ||||||||
PATCH | /api/v1/builder/fonts/{ulid} | Schnitt pflegen — Familie, Stärke, Stil, font-display und die Vorlade-Markierung. Die DATEI bleibt, wie sie ist — ein anderer Schnitt ist eine andere Zeile. | builder.theme.manage | ulid, + body | ||||||||
GET | /api/v1/builder/library-items | Collection of BuilderLibraryItem | builder.page.view · builder.library.manage | page, kind, q | ||||||||
POST | /api/v1/builder/library-items | Bibliotheks-Eintrag anlegen — Pflicht sind name und kind (section\ | page\ | global\ | component). blocksJson ist der gespeicherte Baum; Komponenten tragen zusaetzlich propsSchema (text\ | richtext\ | image\ | link\ | color\ | visibility) und slots (Doc 37 §7.6). | builder.library.manage | + body |
POST | /api/v1/builder/library-items/import | Bibliotheks-Eintrag importieren — Payload = Export-Format {format: "octibuilder-library@1", name, kind, tags?, blocks} (+ optional brandId). Die Herkunft wird in externalRefs.import festgehalten. | builder.library.manage | + body | ||||||||
DELETE | /api/v1/builder/library-items/{ulid} | Delete a BuilderLibraryItem | builder.library.manage | ulid | ||||||||
GET | /api/v1/builder/library-items/{ulid} | Read one BuilderLibraryItem | builder.page.view | ulid | ||||||||
PATCH | /api/v1/builder/library-items/{ulid} | Bibliotheks-Eintrag aendern — Bei kind: global und kind: component werden nach dem Speichern alle aktiven Releases, die das Element verwenden, aus ihrem eingefrorenen Baum neu gebaut („einmal aendern, ueberall wirksam"). | builder.library.manage | ulid, + body | ||||||||
GET | /api/v1/builder/library-items/{ulid}/export | Bibliotheks-Eintrag exportieren — Portables Format {format: "octibuilder-library@1", name, kind, tags, blocks} (+ propsSchema/slots bei kind=component) — 1:1 wieder importierbar. | builder.page.view · builder.library.manage | ulid | ||||||||
GET | /api/v1/builder/pages | Collection of BuilderPage | builder.page.view | page, kind, templateKind, q, order[name], order[updatedAt] | ||||||||
POST | /api/v1/builder/pages | Flaeche anlegen — Pflicht ist name; kind (Default page) bestimmt die Flaechen-Art. kind: template braucht zusaetzlich builder.template.manage, kind: popup zusaetzlich builder.popup.manage. Der Entwurfs-Baum wird per PATCH (blocks) geschrieben. | builder.page.create | + body | ||||||||
DELETE | /api/v1/builder/pages/{ulid} | Delete a BuilderPage | builder.page.delete | ulid | ||||||||
GET | /api/v1/builder/pages/{ulid} | Read one BuilderPage | builder.page.view | ulid | ||||||||
PATCH | /api/v1/builder/pages/{ulid} | Flaeche aendern (Inhalt, SEO, Theme, Entwurfs-Baum) — blocks schreibt den ENTWURFS-Baum: ohne builder.style.edit sind nur Inhalts-Werte bestehender Bausteine aenderbar, ohne builder.lock.override muessen gesperrte Teilbaeume unveraendert bleiben (403 mit Verstoss-Code). version MUSS der zuvor gelesene Stand des Entwurfs-Baums sein — sonst 409 (ein zweiter Bearbeiter war schneller); ohne version wird nicht geprueft. Veroeffentlicht wird separat ueber /publish. | builder.page.update | ulid, + body | ||||||||
POST | /api/v1/builder/pages/{ulid}/ai/translation-suggestions | KI-Übersetzungsvorschlag für eine Ziel-Sprache der Fläche — Payload {targetLocale}. Antwort {sourceLocale, targetLocale, items: [{ref, blockId, blockType, field, source, suggestion}], remaining, aiUsed, contentVersion}. Vorgeschlagen wird nur, was in der Standardsprache steht und in der Ziel-Sprache fehlt (Text-/Mehrzeiler-Felder, Listen-Einträge, Fließtext); gepflegte Fassungen bleiben aussen vor. Schreibt nichts — übernommen wird über POST /v1/builder/pages/{ulid}/translations. Je Lauf höchstens 150 Texte; remaining nennt den Rest. | builder.page.update | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/audit | Pruefhinweise des Entwurfs — Befunde ueber den ENTWURFS-Baum + Theme-Token: {findings: [{severity, code, blockId, context}]}. Das Publizieren blockieren sie nicht (Gestaltungsfreiheit). | builder.page.view | ulid | ||||||||
POST | /api/v1/builder/pages/{ulid}/canvas | Entwurfs-Baum fuer den Live-Canvas rendern — Payload {blocks, locale?}. Antwort {html, baseCss, themeCss, islands, warnings, usedBlockTypes} — Rumpf-Fragment ohne Dokument-Rahmen, ohne DB-Schreiben. baseCss/themeCss sind je Sitzung stabil; die Element-Regeln kompiliert der Editor selbst. | builder.page.view | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/code | Kopf-/Fuss-Code einer Flaeche lesen — Braucht builder.code.embed KONKRET in der Marke der Flaeche. Ohne das Recht 422 — der Code wird auch nicht teilweise gezeigt. | builder.code.embed | ulid | ||||||||
PATCH | /api/v1/builder/pages/{ulid}/code | Kopf-/Fuss-Code einer Flaeche setzen — Merge-PATCH: null = nicht mitgeschickt, leerer String leert das Feld. headCodeConsent/bodyEndCodeConsent nennen die Kategorie des Zustimmungs-Banners; leer = sofort laden (Vorbelegung). Der Code wird UNVERAENDERT ausgeliefert — kein Escaping, kein Sanitizer. Wirksam wird er mit dem naechsten Veroeffentlichen der Flaeche. | builder.code.embed | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/comments | Collection of BuilderPageComment | builder.page.view | ulid, resolved, blockId | ||||||||
POST | /api/v1/builder/pages/{ulid}/comments | Kommentar an der Fläche verfassen — Payload {body, blockId?, parentUlid?, mentionedUserIds?}. blockId verankert den Kommentar am Baustein (leer = flächenweit); eine Antwort (parentUlid) hängt immer am Wurzelkommentar und erbt dessen Anker. | builder.comment.create | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/diff | Entwurf gegen veröffentlichten Stand vergleichen — Antwort {published, hasChanges, added[], changed[], removed[], unchanged, reordered}. published: false = noch nie veröffentlicht (dann ist alles neu). | builder.page.view | ulid, locale | ||||||||
POST | /api/v1/builder/pages/{ulid}/duplicate | Flaeche duplizieren (inkl. Entwurfs-Baum und SEO) — Payload {name?}; ohne name erhaelt die Kopie das Suffix „ (Kopie)". Kopiert werden Entwurfs-Baum, SEO-Felder, Theme-Zuordnung und kind-Konfiguration — Releases nicht (die Kopie ist ein Entwurf). | builder.page.create | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/preview | HTML-Vorschau des Entwurfs — Antwort {html} — komplettes Dokument (Head + Theme-CSS + Rumpf), ohne Kopf-/Fussvorlage, ohne DB-Schreiben. | builder.page.view | ulid, locale | ||||||||
POST | /api/v1/builder/pages/{ulid}/preview-link | Teilbaren Vorschau-Link erzeugen — Payload {locale?, ttlSeconds?}. Antwort {token, url, expiresAt} — url ist die Adresse der veröffentlichten Website mit ?obpreview=<token>; ohne aufgelösten Host bleibt sie leer und der Aufrufer setzt den Host selbst. Laufzeit 1 Stunde bis 14 Tage (Vorbelegung 7 Tage). | builder.page.view | ulid, + body | ||||||||
POST | /api/v1/builder/pages/{ulid}/publish | Veroeffentlichen (sofort oder geplant) — Payload {scheduledFor?: ISO-8601}. Ohne scheduledFor wird der Entwurf JETZT gebaut und aktiviert; mit scheduledFor (Zukunft) wird das Erzeugnis sofort eingefroren und zum Zeitpunkt aktiviert — eine neue Planung ersetzt eine bestehende. | builder.page.publish | ulid, + body | ||||||||
GET | /api/v1/builder/pages/{ulid}/releases | Collection of BuilderRelease | builder.page.view | ulid | ||||||||
POST | /api/v1/builder/pages/{ulid}/rollback | Auf ein aelteres Release zurueckrollen — Payload {releaseUlid}. Das Release muss zu dieser Flaeche gehoeren (sonst 404); es wird OHNE Re-Render wieder das aktive Erzeugnis. | builder.page.publish | ulid, + body | ||||||||
POST | /api/v1/builder/pages/{ulid}/translations | Bestätigte Übersetzungen in den Entwurf übernehmen — Payload {targetLocale, items: [{ref, text}], expectedVersion?} — ref aus dem Vorschlag. Geschrieben wird nur, wo die Ziel-Sprache noch leer ist; eine inzwischen gepflegte Fassung bleibt unberührt und zählt in skipped. Mit expectedVersion antwortet ein fremd geänderter Entwurf mit 409. Antwort {applied, skipped, contentVersion}. | builder.page.update | ulid, + body | ||||||||
POST | /api/v1/builder/pages/{ulid}/unpublish | Von der Auslieferung nehmen — Entwurf und Historie bleiben unberuehrt; ohne aktives Release 409. | builder.page.publish | ulid, + body | ||||||||
GET | /api/v1/builder/starter-templates | Mitgelieferte Start-Vorlagen des Baukastens — Seiten (blocks als Entwurfs-Baum), Abschnitte (blocks zum Einfuegen) und Erscheinungsbilder (tokens fuer ein neues Theme). Uebernehmen ueber POST /v1/builder/pages + PATCH blocks bzw. POST /v1/builder/themes. | builder.page.view · builder.theme.manage | kind | ||||||||
GET | /api/v1/builder/style-classes | Stil-Klassen — Benannte Klassen (class) und Tag-Grundstile (tag). comboParents macht eine Klasse zur Kombi-Klasse. | builder.class.view | brandId, kind, q | ||||||||
POST | /api/v1/builder/style-classes | Create a BuilderStyleClass | builder.class.manage | + body | ||||||||
DELETE | /api/v1/builder/style-classes/{ulid} | Stil-Klasse löschen — Soft-Delete. Flächen, die sie referenzieren, rendern danach ohne sie weiter — die Referenz fällt still weg (fail-safe). | builder.class.manage | ulid | ||||||||
GET | /api/v1/builder/style-classes/{ulid} | Read one BuilderStyleClass | builder.class.view | ulid | ||||||||
PATCH | /api/v1/builder/style-classes/{ulid} | Update a BuilderStyleClass | builder.class.manage | ulid, + body | ||||||||
GET | /api/v1/builder/themes | Collection of BuilderTheme | builder.page.view · builder.theme.manage | page | ||||||||
POST | /api/v1/builder/themes | Theme anlegen — Pflicht ist name. isDefault: true macht dieses Theme zum Standard seiner Marke und nimmt anderen Themes derselben Marke den Default. | builder.theme.manage | + body | ||||||||
DELETE | /api/v1/builder/themes/{ulid} | Delete a BuilderTheme | builder.theme.manage | ulid | ||||||||
GET | /api/v1/builder/themes/{ulid} | Read one BuilderTheme | builder.page.view | ulid | ||||||||
PATCH | /api/v1/builder/themes/{ulid} | Theme aendern (versioniert) — Vor JEDEM Update wird der alte Stand als BuilderThemeVersion (versionNo = bisherige cssVersion) festgehalten, danach hebt cssVersion (Cache-Busting, ENT-BUILDER-10). | builder.theme.manage | ulid, + body | ||||||||
POST | /api/v1/builder/themes/{ulid}/restore | Alten Theme-Stand wiederherstellen — Payload {versionNo}. Der aktuelle Stand wird als NEUE Version festgehalten (lueckenlose Historie), dann der alte Stand ins Theme kopiert und cssVersion gehoben. | builder.theme.manage | ulid, + body | ||||||||
GET | /api/v1/builder/themes/{ulid}/versions | Versions-Historie des Themes — Alle festgehaltenen Staende, neueste zuerst — jede Aenderung am Theme hinterlaesst genau eine Zeile. | builder.page.view · builder.theme.manage | ulid |
Purpose texts that do not follow the standard pattern are taken verbatim from the interface description in the code.