API

API-Konfiguration

Zunächst muss die API im Backoffice aktiviert und konfiguriert werden.

Konfiguration öffnen:
Module > PrestaBlog > Konfiguration > Tools > API

Verfügbare Einstellungen:

• API aktivieren: Hauptschalter. Solange deaktiviert, beantwortet die API keine Anfragen.
• API-Schlüssel: klicke auf „Neuen Schlüssel generieren“. Der Schlüssel wird nur einmal angezeigt - kopiere ihn sofort, danach ist er nicht mehr abrufbar. Gespeichert wird nur sein kryptografischer Fingerabdruck (SHA-256). Wenn du den Schlüssel verlierst, generiere einen neuen.
• Neue Artikel automatisch aktivieren: legt fest, ob über die API erstellte Artikel sofort veröffentlicht oder als Entwurf gespeichert werden, wenn die Anfrage diesen Parameter nicht explizit setzt.
• Rate Limit: maximale Anzahl von Anfragen pro Minute und IP-Adresse (Standard: 60).
• Bild-Sicherheit: blockiert das Herunterladen von Bildern aus privaten/internen IP-Bereichen. Empfohlen für Installationen, die im Internet erreichbar sind.
• Hinter einem Proxy: aktivieren, wenn dein Shop hinter Cloudflare, einem Reverse Proxy oder einem CDN liegt, damit die Client-IP korrekt behandelt wird.
• Log-Level: None deaktiviert Logs. Security protokolliert fehlgeschlagene Authentifizierungen und Blockierungen. Debug protokolliert alle Anfragen (nur temporär zur Diagnose verwenden).
• Zulässige CORS-Origins: nur nötig, wenn eine Web-App auf einer anderen Domain die API aus dem Browser aufruft. In den meisten Fällen leer lassen.

API-Berechtigungen

Im Bereich API-Berechtigungen kannst du exakt festlegen, was der API-Schlüssel tun darf. Jede Operation kann unabhängig aktiviert oder deaktiviert werden - sowohl für Artikel als auch für Kategorien.

• Erstellen von Artikeln / Kategorien erlauben: erlaubt POST-Anfragen zum Erstellen neuer Inhalte.
• Bearbeiten von Artikeln / Kategorien erlauben: erlaubt PUT-Anfragen zum Aktualisieren bestehender Inhalte.
• Löschen von Artikeln / Kategorien erlauben: erlaubt DELETE-Anfragen. Deaktiviere dies, wenn du versehentliche Löschungen durch einen KI-Agenten oder ein Dritt-Skript verhindern möchtest.

Nutzung mit einem KI-Agenten (empfohlen)

Du bist kein Entwickler oder möchtest keinen Code schreiben? Die einfachste Methode ist die Nutzung eines KI-Agenten wie Claude über das MCP-Protokoll (Model Context Protocol). Der Agent weiß genau, welche Aufrufe nötig sind, kümmert sich um die Authentifizierung und versteht deine Anweisungen in natürlicher Sprache.

1. API aktivieren und Schlüssel generieren

Im PrestaBlog-Backoffice: Tools > API. Aktiviere die API, klicke auf „Neuen Schlüssel generieren“ und kopiere den angezeigten Schlüssel - danach ist er nicht mehr abrufbar.

2. MCP-Verbindungs-URL erstellen

Die Verbindungs-URL hat folgendes Format:

https://prestablog-mcp.prestablog.workers.dev/mcp?key=YOUR_KEY&shop=https://your-shop.com

Ersetze YOUR_KEY durch deinen generierten Schlüssel und https://your-shop.com durch die URL deines Shops.

Nicht zu verwechseln mit der „API-URL“, das ist eine andere URL für direkte Aufrufe.

3. Mit Claude konfigurieren

In Claude klicke oben links auf Customize, dann auf Connectors,
anschließend oben in der Spalte auf + und dann auf Add a custom connector.

Eintragen:

• Name: beliebig (z. B. PrestaBlog API)
• URL: die in Schritt 2 erstellte MCP-Verbindungs-URL

Bestätigen. Claude kann nun auf deinen Blog zugreifen und Artikel sowie Kategorien direkt erstellen, bearbeiten und löschen.

Beispiele für Anfragen an Claude:

• „Erstelle einen Artikel über Sommerschuhe in der Kategorie Mode“
• „Liste die 10 zuletzt veröffentlichten Artikel“
• „Ändere den Titel von Artikel 42“
• „Erstelle eine neue Kategorie ‚News‘ mit dieser Beschreibung“
• „Lösche Kategorie 5“

4. Mit Windsurf konfigurieren

In Windsurf öffne das Cascade-Panel, klicke oben rechts auf ... und dann auf das MCPs-Icon (letztes Icon unten rechts im Menü). Es öffnet sich ein Editor. Füge die folgende Konfiguration hinzu, nachdem du die URL korrekt erstellt hast (siehe Schritt 2):

{
  "mcpServers": {
    "prestablog": {
      "serverUrl": "https://prestablog-mcp.prestablog.workers.dev/mcp?key=YOUR_KEY&shop=https://your-shop.com"
    }
  }
}

Speichern. Cascade zeigt unten im Panel 1 MCP an und bestätigt damit, dass die Verbindung aktiv ist.

Beispiele für Anfragen an Cascade:

• „Erstelle einen Artikel über Sommerschuhe in der Kategorie Mode“
• „Liste die 10 zuletzt veröffentlichten Artikel“
• „Ändere den Titel von Artikel 42“
• „Erstelle eine neue Kategorie ‚News‘ mit dieser Beschreibung“
• „Lösche Kategorie 5“

Authentifizierung (REST)

Jede Anfrage muss den API-Schlüssel in einem HTTP-Header enthalten. Zwei Formate werden unterstützt:

Authorization: Bearer YOUR_API_KEY

oder

X-Api-Key: YOUR_API_KEY

Automatische Sperre: nach 5 fehlgeschlagenen Authentifizierungsversuchen von derselben IP wird diese für 1 Stunde gesperrt. Diese Dauer ist in den API-Einstellungen konfigurierbar.

Artikel

Artikel auflisten

GET /prestablog-api/articles

Gibt die paginierte Liste der Artikel zurück. Verfügbare Parameter: lang (Sprach-ID), page, per_page (max. 100), active (1 = nur veröffentlicht), category (Kategorie-ID), search (Suche im Titel), sort (date, title, id), order (asc, desc).

curl -X GET "https://your-shop.com/prestablog-api/articles?lang=1&page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_KEY"

Artikeldetails

GET /prestablog-api/articles/{id}

Gibt alle Daten eines Artikels zurück: mehrsprachige Felder, Kategorien, verknüpfte Produkte, verwandte Artikel, Inhaltsverzeichnis.

curl -X GET "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Artikel erstellen

POST /prestablog-api/articles

Minimales Beispiel:

curl -X POST "https://your-shop.com/prestablog-api/articles" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "My article",
        "content": "<h2>Introduction</h2><p>Article content.</p>"
      }
    },
    "categories": [1],
    "active": true
  }'

Vollständiges Beispiel mit Bild, Mehrsprachigkeit und Metadaten:

{
  "languages": {
    "1": {
      "title": "My article",
      "introduction": "Short text displayed in listings",
      "content": "<h2>Section</h2><p>Full HTML content.</p>",
      "meta_title": "My article - SEO Title",
      "meta_description": "Search engine description",
      "meta_keywords": "word1, word2",
      "link_rewrite": "my-article"
    },
    "2": {
      "title": "My article",
      "introduction": "Short text displayed in listings",
      "content": "<h2>Section</h2><p>Full HTML content.</p>"
    }
  },
  "categories": [2, 5],
  "active": true,
  "date": "2026-06-15 09:00:00",
  "enable_toc": true,
  "author_id": 1,
  "image": {
    "url": "https://example.com/image.jpg"
  }
}

Verfügbare Felder:

Artikel aktualisieren

PUT /prestablog-api/articles/{id}

Teilaktualisierung: nur Felder in der Anfrage werden geändert. Nicht übermittelte Felder behalten ihren aktuellen Wert. Bei Sprachen werden nur die im Payload enthaltenen aktualisiert.

curl -X PUT "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false,
    "languages": {
      "1": {
        "title": "New title"
      }
    }
  }'

Artikel löschen

DELETE /prestablog-api/articles/{id}

Löscht den Artikel und alle zugehörigen Daten: Bilder (alle Varianten), Kategorien, verknüpfte Produkte, verwandte Artikel.

curl -X DELETE "https://your-shop.com/prestablog-api/articles/18" \
  -H "Authorization: Bearer YOUR_KEY"

Artikelbild

POST /prestablog-api/articles/{id}/image

Drei Methoden stehen je nach Kontext zur Verfügung:

Remote-URL (Bild ist online gehostet):

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/image.jpg"}'

Lokale Datei (Multipart-Upload):

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/image.jpg"

Base64 (Fallback):

Hinweis: Base64 ist sehr groß und kann bei komplexen Bildern schwer zu handhaben sein. Wenn möglich, Upload über eine Remote-URL bevorzugen.

curl -X POST "https://your-shop.com/prestablog-api/articles/18/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"base64": "/9j/4AAQSkZJRg...", "filename": "photo.jpg"}'

Kategorien

Die API ermöglicht das Erstellen, Anzeigen, Aktualisieren und Löschen von Kategorien, genau wie bei Artikeln.

Kategorien auflisten

GET /prestablog-api/categories

Gibt Kategorien standardmäßig als Baumstruktur zurück. Verwende flat=1 für eine flache Liste, active=1 nur für aktive, lang für die Sprache.

curl -X GET "https://your-shop.com/prestablog-api/categories?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Kategorie-Details

GET /prestablog-api/categories/{id}

Gibt alle Kategorie-Daten zurück: mehrsprachige Felder, Artikelanzahl, zugeordnete Kundengruppen.

Kategorie erstellen

POST /prestablog-api/categories

Minimales Beispiel:

curl -X POST "https://your-shop.com/prestablog-api/categories" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "News"
      }
    },
    "active": true
  }'

Vollständiges Beispiel:

{
  "languages": {
    "1": {
      "title": "News",
      "description": "<p>All news from our shop.</p>",
      "meta_title": "News - SEO Title",
      "meta_description": "SEO description of the category",
      "meta_keywords": "news",
      "link_rewrite": "news"
    },
    "2": {
      "title": "News",
      "description": "<p>All the latest news from our shop.</p>",
      "link_rewrite": "news"
    }
  },
  "parent": 0,
  "position": 1,
  "active": true,
  "image": {
    "url": "https://example.com/category.jpg"
  }
}

Verfügbare Felder:

Kategorie aktualisieren

PUT /prestablog-api/categories/{id}

Teilsaktualisierung: nur Felder in der Anfrage werden geändert.

curl -X PUT "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "languages": {
      "1": {
        "title": "New category name",
        "description": "<p>New description.</p>"
      }
    }
  }'

Kategorie löschen

DELETE /prestablog-api/categories/{id}

Löscht die Kategorie und alle zugehörigen Daten: Bild, Verknüpfungen mit Artikeln, Kundengruppen.

curl -X DELETE "https://your-shop.com/prestablog-api/categories/1" \
  -H "Authorization: Bearer YOUR_KEY"

Kategoriebild

POST /prestablog-api/categories/{id}/image

Die gleichen drei Methoden wie bei Artikeln: Remote-URL, lokale Datei (Multipart) oder Base64.

Hinweis: Base64 ist sehr groß und kann bei komplexen Bildern schwer zu handhaben sein. Wenn möglich, Upload über eine Remote-URL bevorzugen.

curl -X POST "https://your-shop.com/prestablog-api/categories/1/image" \
  -H "Authorization: Bearer YOUR_KEY" \
  -F "file=@/path/to/category.jpg"

Autoren

Autoren sind über die API nur lesbar. Sie müssen im PrestaBlog-Backoffice angelegt werden.

• GET /prestablog-api/authors - alle Autoren auflisten
• GET /prestablog-api/authors/{id} - Autor-Details mit mehrsprachigen Biografien

curl -X GET "https://your-shop.com/prestablog-api/authors?lang=1" \
  -H "Authorization: Bearer YOUR_KEY"

Fehlercodes

Alle Fehlerantworten folgen diesem Format:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Lesbare Fehlermeldung",
    "details": { "field": "languages.1.title" }
  }
}

Rate Limit: bei Überschreitung enthält die 429-Antwort den Header Retry-After, der angibt, wie viele Sekunden vor einem erneuten Versuch zu warten ist. Jede Antwort enthält außerdem die Header X-RateLimit-Limit und X-RateLimit-Remaining.

Python-Integration

Für Python-Entwickler ermöglicht die Bibliothek requests die Interaktion mit der API in wenigen Zeilen.

pip install requests

import requests

BASE = "https://your-shop.com/prestablog-api"
KEY = "YOUR_KEY"
headers = {"Authorization": f"Bearer {KEY}"}

# Artikel auflisten
r = requests.get(f"{BASE}/articles", headers=headers, params={"lang": 1, "per_page": 10})
print(r.json())

# Artikel erstellen
r = requests.post(f"{BASE}/articles", headers=headers, json={
    "languages": {"1": {"title": "My article", "content": "<p>Content</p>"}},
    "categories": [1],
    "active": True
})
print(r.json())

# Bild aus einer lokalen Datei hochladen
with open("image.jpg", "rb") as f:
    r = requests.post(f"{BASE}/articles/18/image", headers=headers, files={"file": f})
print(r.json())