Schritt für Schritt: Page per API aktualisieren

In diesem Beispiel aktualisierst du eine bestehende Page komplett über die API: Du legst einen Link an, setzt ihn an die erste Stelle, änderst den Button-Stil, prüfst den Entwurf und veröffentlichst ihn. Die Befehle laufen in jeder Shell mit curl und jq.

#1. API-Key anlegen

1. Öffne im Dashboard „Callback & API“
2. Klicke auf „+ Neuen Key erstellen“
3. Wähle bei „Pages“ und „Links“ jeweils „Schreiben“ (das schließt Lesen ein)
4. Klicke auf „Key erstellen“ und kopiere das Key-Secret
5. Kopiere die Key-ID aus der Liste

Leg beide Werte als Umgebungsvariablen ab, nicht im Skript:

export LH_KEY_ID="6F668EA6598B0692"
export LH_KEY_SECRET="lt_…"
export API="https://dock.at-harbor.com"

#2. Access-Token holen

LH_TOKEN=$(curl -sS -X POST "$API/v1/token" \
  -H "Content-Type: application/json" \
  -d "{\"key_id\":\"$LH_KEY_ID\",\"key_secret\":\"$LH_KEY_SECRET\"}" \
  | jq -r .token)

Das Token gilt 15 Minuten. Läuft dein Skript länger, hol zwischendurch ein neues.

#3. Page finden

curl -sS "$API/v1/pages" -H "Authorization: Bearer $LH_TOKEN" \
  | jq '.items[] | {id, handle, title, status, current_version}'

Merk dir die id der Page. Im Beispiel ist es 42:

PAGE_ID=42

#4. Link anlegen

LINK_ID=$(curl -sS -X POST "$API/v1/pages/$PAGE_ID/links" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Herbst-Sale","target_url_template":"https://shop.example.com/herbst","enabled":true}' \
  | jq -r .id)
echo "Neuer Link: $LINK_ID"

Die API antwortet mit HTTP 201 und der neuen ID. Neue Links stehen am Ende der Liste. Ist das Link-Limit deines Plans erreicht, kommt 409 link_limit_reached.

#5. Link nach oben setzen

curl -sS -X POST "$API/v1/pages/$PAGE_ID/links/reorder" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"order\":[$LINK_ID]}"

Es reicht, die IDs zu schicken, die nach vorne sollen. Alle anderen Links behalten ihre Reihenfolge dahinter.

#6. Design im Entwurf ändern

theme_config wird beim PATCH komplett ersetzt. Deshalb liest du den Entwurf zuerst, änderst nur den gewünschten Wert und schickst das ganze Objekt zurück:

THEME=$(curl -sS "$API/v1/pages/$PAGE_ID/draft" -H "Authorization: Bearer $LH_TOKEN" \
  | jq -c '(.theme_config // {}) | .button_style = "pill"')

curl -sS -X PATCH "$API/v1/pages/$PAGE_ID/draft" \
  -H "Authorization: Bearer $LH_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"theme_config\":$THEME}"

Für button_style sind rounded, pill und square erlaubt. Weitere Felder von theme_config sind unter anderem bg_color, text_color, button_color, button_text_color und background.

#7. Entwurf prüfen

curl -sS "$API/v1/pages/$PAGE_ID/draft/validate" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"valid":true,"issues":[]}

Ist valid false, nennt issues die Probleme. Behebe sie, bevor du veröffentlichst. Ob der Entwurf überhaupt vom Live-Stand abweicht, zeigt GET /v1/pages/$PAGE_ID im Feld has_unpublished_changes – ist es false, kannst du das Veröffentlichen überspringen.

#8. Veröffentlichen

curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"
# → {"ok":true,"version":8,"checksum":"…"}

Jetzt sehen Besucher den neuen Stand – inklusive des neuen Links, der Reihenfolge und des Designs. Hast du einen Webhook für page.published, bekommt er jetzt eine Zustellung. Lässt sich der Entwurf nicht veröffentlichen, antwortet die API mit 409 draft_not_publishable und der Liste in details.issues.

#9. Rückgängig machen

Gefällt das Ergebnis nicht, holst du die vorherige Version zurück in den Entwurf und veröffentlichst erneut:

curl -sS -X POST "$API/v1/pages/$PAGE_ID/versions/7/restore" -H "Authorization: Bearer $LH_TOKEN"
curl -sS -X POST "$API/v1/pages/$PAGE_ID/publish" -H "Authorization: Bearer $LH_TOKEN"

Statt einer Versionsnummer kannst du current angeben: Das verwirft alle Entwurfsänderungen seit der letzten Veröffentlichung. Die Wiederherstellung übernimmt Design, Template, Custom CSS, SEO, Blöcke und Links; Titel, Handle und Sichtbarkeit sind nicht versioniert.

#Häufige Fehler

400 bad_request

Der Header Content-Type: application/json fehlt. curl -d sendet ohne ihn einen anderen Typ.

401 invalid_token

Das Token ist nach 15 Minuten abgelaufen. Hol ein neues.

403 insufficient_scope

Dem Key fehlt ein Scope, etwa „Schreiben“ bei Links.

Design plötzlich zurückgesetzt

theme_config wurde mit nur einem Feld geschickt und hat das ganze Theme ersetzt. Schick das vollständige Theme erneut, oder verwirf mit restore current alle Entwurfsänderungen seit der letzten Veröffentlichung.

Alle Codes erklärt Fehlerformat und Fehlercodes, alle Endpunkte stehen unter Endpunkte nach Bereich.