API-Referenz

Eine kleine, stabile REST-API zum Verwalten von Überwachungen und Kanälen sowie zum Abfragen von Änderungen. Derselbe Funktionsumfang wie das Dashboard.

Basis-URL

Produktion: https://api.pagedeltas.com. Alle Endpunkte sind mit /api präfixiert. Erfolgreiche Antworten sind JSON.

Authentifizierung

Erstellen Sie einen Schlüssel über Settings → API keys (Editor- oder Admin-Rolle erforderlich). Der Schlüssel wird bei der Erstellung nur einmal angezeigt — kopieren Sie ihn sofort. Um einen Schlüssel zu widerrufen, löschen Sie ihn auf derselben Seite.

Authorization: Bearer pdt_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel sind auf die Organisation beschränkt, die sie erstellt hat, und agieren innerhalb dieser Organisation mit Admin-Zugriff, unabhängig von einem Benutzer. Sie sind nicht an ein Mitglied gebunden, sodass das Entfernen eines Teammitglieds die Schlüssel der Organisation nicht widerruft — löschen Sie den Schlüssel selbst, um den Zugriff zu sperren.

Fehler

Fehler geben einen Status ungleich 2xx zurück. Authentifizierungs- und Berechtigungsfehler werden als kurze Klartextmeldung zurückgegeben (z. B. unauthorized, forbidden); Kontingent- und Ratenbegrenzungsfehler geben einen kleinen JSON-Body mit einer Meldung und den relevanten Zahlen zurück. Parsen Sie keinen festen Fehlerumschlag — verzweigen Sie anhand des HTTP-Statuscodes:

400 — fehlerhafte Anfrage (ungültiges JSON, ungültige URL, fehlendes Feld).
401 — fehlende oder ungültige Anmeldedaten.
403 — authentifiziert, aber Ihre Rolle hat keine Berechtigung für diese Aktion.
404 — Ressource fehlt oder nicht in Ihrer Organisation.
409 — Konflikt (z. B. die Überwachung ist aufgrund wiederholter Blockierungen pausiert).
422 — ein Kontingent würde überschritten (z. B. das Überwachungslimit Ihres Tarifs). Der JSON-Body enthält current und limit.
429 — ratenbegrenzt (manuelle Prüfungen). Warten Sie und versuchen Sie es nach der in Retry-After angegebenen Verzögerung erneut.

Beispiel für einen Kontingentfehler (422):

{
  "error": "plan_url_limit exceeded",
  "current": 100,
  "limit": 100,
  "message": "Creating this monitor would exceed your plan's monitor limit (100)."
}

Endpunkt-Referenz

Methode & Pfad	Beschreibung
`GET /api/monitors`	Überwachungen in Ihrer Organisation auflisten.
`POST /api/monitors`	Eine einzelne Überwachung erstellen.
`GET /api/monitors/{id}`	Eine einzelne Überwachung abrufen.
`PATCH /api/monitors/{id}`	`url`, `nl_description`, `filter_prompt`, `css_selector`, `xpath_selector`, `status` aktualisieren.
`DELETE /api/monitors/{id}`	Eine Überwachung und ihren Verlauf löschen.
`POST /api/monitors/{id}/check-now`	Eine sofortige Prüfung in die Warteschlange stellen und den Zeitplan umgehen (ratenbegrenzt, siehe unten).
`GET /api/monitors/{id}/changes`	Erkannte Änderungen für eine Überwachung auflisten (unterstützt `?limit=`, max. 100).
`POST /api/monitors/import`	Massenimport per Multipart-CSV-Upload (`file`-Feld).
`POST /api/monitors/bulk-pause`, `bulk-resume`, `bulk-delete`	Eine Aktion auf eine Liste von Überwachungs-IDs anwenden.
`GET\|PUT /api/monitors/{id}/alert-channels`	Kanal-Overrides einer Überwachung lesen oder ersetzen.
`GET /api/alert-channels`	Benachrichtigungskanäle auflisten.
`POST /api/alert-channels`	Einen Kanal erstellen.
`PATCH\|DELETE /api/alert-channels/{id}`	Einen Kanal aktualisieren oder löschen.
`POST /api/alert-channels/{id}/test`	Eine Test-Payload senden, um die Zustellung zu überprüfen.
`GET\|POST /api/sitemap-monitors`	Sitemap-Überwachungen auflisten oder erstellen.
`POST /api/sitemap-monitors/import`	Sitemap-Überwachungen per Multipart-CSV-Upload massenweise erstellen (`file`-Feld).
`GET\|POST\|DELETE /api/tokens`	API-Schlüssel auflisten, erstellen und löschen.
`GET /api/billing/plan`	Aktueller Tarif und Limits Ihrer Organisation.
`GET /api/plans`	Öffentlich — verfügbare Tarife auflisten (keine Authentifizierung erforderlich).

Beispiel — eine Überwachung erstellen

curl -X POST https://api.pagedeltas.com/api/monitors \
  -H "Authorization: Bearer $PAGEDELTAS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "nl_description": "Competitor pricing; alert on plan or price changes",
    "filter_prompt": "Alert on plan or price changes; ignore copy tweaks",
    "channel_ids": []
  }'

Optionale Felder: filter_prompt, css_selector, xpath_selector, is_pdf und channel_ids (Kanal-Overrides pro Überwachung; weglassen, um die Standardeinstellungen der Organisation zu verwenden). Es gibt kein frequency — die Planung erfolgt adaptiv.

Beispiel — auf Änderungen abfragen

GET /api/monitors/01HW2X.../changes?limit=50
Authorization: Bearer $PAGEDELTAS_TOKEN

Gibt die neuesten Änderungen zuerst zurück (Standard 50, max. 100). Es gibt keinen Cursor — paginieren Sie, indem Sie limit anpassen und das letzte bereits gesehene detected_at nachverfolgen.

{
  "changes": [
    {
      "id": "01HW3...",
      "detected_at": "2026-06-01T08:42:00Z",
      "summary": "Pro plan increased from $29 to $39/month."
    }
  ]
}

Ratenbegrenzungen

Derzeit gibt es keine Ratenbegrenzungen pro Schlüssel für die Lese- und Schreibendpunkte. Die einzige Ausnahme sind manuelle Prüfungen:

Check-now: 1 Anfrage / Minute / Überwachung.

Wenn Sie dieses Limit erreichen, lautet die Antwort 429 mit einem Retry-After-Header in Sekunden. Begrenzen Sie sich bitte trotzdem auf den anderen Endpunkten sinnvoll selbst.

Versionierung

Wir sind bestrebt, diesen Funktionsumfang stabil zu halten. Neue Felder und Endpunkte können ohne Vorankündigung hinzugefügt werden, schreiben Sie daher Clients, die unbekannte JSON-Felder ignorieren.