API-Dokumentation

Drei Ziele in einer Überwachung: zwei bekannte Seiten, ein Bereich einer Website und zwei Suchanfragen. Speichern Sie den Body als monitor.json und schicken Sie ihn mit -d @monitor.json; Umlaute kommen so auf jedem System richtig an.

{
  "name": "Markt und Wettbewerb",
  "schedule": {"cron": "0 7 * * 1-5", "timezone": "Europe/Berlin"},
  "targets": [
    {"type": "scrape",
     "urls": ["https://example.com/preise", "https://example.com/lieferung"],
     "scrapeOptions": {"onlyMainContent": true,
                       "formats": ["markdown", {"type": "chunks", "profile": "balanced"}]}},
    {"type": "crawl",
     "url": "https://example.com/produkte",
     "crawlOptions": {"limit": 30, "maxDiscoveryDepth": 2, "excludePaths": ["^/produkte/archiv/.*"]}},
    {"type": "search",
     "queries": ["Example GmbH Preise", "Example GmbH neues Produkt"],
     "searchWindow": "24h", "maxResults": 10, "excludeDomains": ["example.com"]}
  ],
  "goal": "Wichtig sind neue oder geänderte Preise, neue Produkte und geänderte Lieferbedingungen. Layout, Datumsangaben und Tippfehler sind unwichtig.",
  "webhook": {
    "url": "https://example.com/ragfeed-webhook",
    "headers": {"X-Ihr-Token": "geheim"},
    "metadata": {"projekt": "markt"},
    "events": ["monitor.page", "monitor.check.completed"]
  },
  "notification": {"email": {"enabled": true, "recipients": ["einkauf@example.com", "vertrieb@example.com"], "includeDiffs": true}},
  "retentionDays": 60
}

curl -X POST https://api.ragfeed.de/v2/monitor \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d @monitor.json

Das Beispiel zählt 2 + 30 + 10 = 42 überwachte Seiten. Zusätzliche Felder wie origin aus den SDKs werden ignoriert.

Geben Sie genau eines an: cron (5 Felder: Minute, Stunde, Tag, Monat, Wochentag; mit Listen, Bereichen, Schritten und Namen wie mon oder jan, dazu @hourly, @daily, @weekly, @monthly) oder text. timezone ist ein IANA-Name wie Europe/Berlin, Standard UTC. Die Antwort nennt immer den cron-Ausdruck, ein Text bleibt in schedule.text stehen.

• Texte auf Englisch: every 30 minutes, every 15 minutes starting at :07, hourly, every 2 hours, daily, daily at 9:00, daily at 9am, weekly, every monday at 8:00.
• Auf Deutsch: alle 30 Minuten, stündlich, alle 2 Stunden, täglich, täglich um 9 Uhr, wöchentlich, jeden Montag um 8:00.
• Texte ohne feste Uhrzeit (etwa hourly) bekommen eine feste Minute, die sich aus der ID der Überwachung ergibt. So starten nicht alle Prüfungen gleichzeitig.
• Der kürzeste Abstand zwischen zwei Terminen muss zu Ihrem Plan passen (Limits), sonst 400 SCHEDULE_TOO_FREQUENT. Nach einem Wechsel in einen kleineren Plan hält der Zeitplaner dessen Abstand ein und lässt Termine aus.
• Sommerzeit: Eine Uhrzeit, die in der Umstellungsnacht nicht existiert, läuft zum Zeitpunkt der Umstellung; eine doppelte Uhrzeit läuft einmal.

Mit einem goal bewertet eine KI jede geänderte Seite (anhand des Unterschieds, höchstens 12.000 Zeichen) und jeden neuen Suchtreffer (Titel, Auszug, Suchanfrage): Ist die Änderung für Ihr Ziel wesentlich oder nicht wesentlich? Die Seite trägt dann isMeaningful und eine judgment:

"judgment": {
  "meaningful": true,
  "confidence": "high",               // high | medium | low
  "reason": "Der Preis für den Tarif Basis steigt von 9 auf 12 Euro.",
  "meaningfulChanges": [{"type": "changed", "before": "9 €", "after": "12 €", "reason": "Preiserhöhung"}]   // added | removed | changed
}

• Kosten: 2 Credits pro bewerteter Seite oder bewertetem Treffer, berechnet nach einer verwertbaren Antwort.
• Wenn die KI nicht antworten kann (keine KI auf dem Server, Tageskontingent des kostenlosen Plans aufgebraucht, Dienst gestört, unbrauchbare Antwort, zu wenig Credits), bleibt judgment leer, die Seite zählt als wesentlich (isMeaningful: true), damit nichts verloren geht, und es wird nichts berechnet. metadata.judgeDegraded ist dann true, metadata.judgeDegradedReason nennt den Grund: llm_not_configured, free_ai_allowance_used, free_ai_budget_used, llm_unavailable, llm_error, invalid_answer oder not_enough_credits.
• Kostenloser Plan: Die Bewertung zählt zum Tageskontingent der KI-Formate (100.000 Token, siehe KI-Auswertung).
• Wirkung: Webhooks bekommen jede gemeldete Seite mit isMeaningful, Sie filtern selbst. Die E-Mail lässt nicht wesentliche Seiten weg und entfällt, wenn nichts Wesentliches übrig bleibt.

Jede Prüfung hat trigger (scheduled oder manual), scheduledFor, startedAt, finishedAt, estimatedCredits (Schätzung), actualCredits, billingStatus (confirmed: berechnet, not_applicable: nichts berechnet, released: ausgesetzt), summary mit der Zahl der Seiten je Status, targetResults je Ziel, notificationStatus (was mit der E-Mail geschah) und, wenn Webhooks verschickt wurden, webhookDeliveries (Anzahl delivered, pending, failed, cancelled, bei Problemen lastError und lastStatusCode).

• Vergleich: Hauptinhalt als Markdown; Leerzeichen am Zeilenende und mehrere Leerzeilen zählen nicht. Mit changeTracking im JSON-Modus zählen nur die Felder Ihres Schemas, gemischt mit "modes": ["git-diff", "json"] beides.
• diff: diff.text ist ein Unified Diff (--- previous, +++ current), diff.json dieselben Änderungen als Struktur (files → chunks → changes mit add, del, normal und Zeilennummern). Im JSON-Modus steht in diff.json pro geändertem Feld {"previous": …, "current": …} und in snapshot.json das ganze Ergebnis. Sehr lange Unterschiede werden bei 200.000 Zeichen gekürzt (metadata.diffTruncated).
• metadata: title, creditsUsed, judgeCredits, finalUrl (nach Weiterleitung), rebaselined (neuer Ausgangsstand nach geänderten Optionen des Ziels oder einer neuen Verarbeitung bei Ragfeed: unverändert, ohne Meldung), notFoundByCrawl; bei Suchtreffern query, description, publishedAt und searchStatus (alert: relevant oder nicht bewertet, ignored: als nicht wesentlich bewertet).
• Websites: Entfernte Seiten meldet eine Prüfung nur, wenn sie die Website vollständig gesehen hat: keine Seite und keine Sitemap fehlgeschlagen, Limit nicht erreicht, genug Credits (targetResults[].removalCheck: done oder skipped). Dazu stehen dort discovered, limitReached, robotsBlocked und brokenLinks (Links auf Seiten, die es nie gab; sie erzeugen keine Fehlerseite). Brauchen includePaths oder excludePaths zu viel Rechenzeit, folgt die Prüfung keinen weiteren Links (pathPatternsStopped: true; entfernte Seiten werden dann nicht gemeldet).
• Suchen: Nur Treffer, die das Ziel noch nicht gemeldet hat, werden zu Seiten mit Status new; bekannte zählen als unverändert. targetResults nennt resultCount, newResults, matches, searchCredits und judgeCredits.

Neue und geänderte Seiten tragen chunkDiff: welche Chunks der Seite neu, weg oder anders sind und was Ihre Vektordatenbank dafür tun muss. Gerechnet wird mit den Einstellungen des Formats chunks im Ziel, ohne sie mit den Standardwerten. Das Vorgehen dahinter, auch ohne Überwachung: Vektordatenbank aktuell halten.

"chunkDiff": {
  "added":   [{"id": "…", "hash": "…", "heading": "Preise › Basis"}],        // Inhalt neu
  "removed": [{"id": "…", "hash": "…", "heading": "Preise › Alt"}],          // Inhalt weg
  "changed": [{"id": "…", "hash": "…", "heading": "…", "previousHash": "…"}], // gleiche ID, anderer Inhalt
  "upsert":  ["…"],   // diese IDs neu schreiben
  "delete":  ["…"]    // diese IDs löschen
}

upsert und delete arbeiten mit den IDs, die von der Position abhängen: Kommt oben ein Abschnitt dazu, bekommen alle folgenden IDs neuen Inhalt, und IDs über die neue Anzahl hinaus fallen weg. added, removed und changed vergleichen dagegen den Inhalt über den hash; nur diese Abschnitte müssen Sie neu einbetten. Die Texte selbst liefert die Überwachung nicht mit: Rufen Sie die Seite mit denselben Chunk-Einstellungen über /v2/scrape ab (1 Credit) und schreiben Sie die Chunks, deren id in upsert steht. Passt ein hash nicht, hat sich die Seite inzwischen erneut geändert; die nächste Prüfung meldet das.

• monitor.page für jede Seite, die nicht unverändert ist: neu, geändert, entfernt oder Fehler, auch wenn die KI sie als nicht wesentlich bewertet. Unveränderte Seiten senden nichts.
• monitor.check.completed nach jeder Prüfung mit dem Status completed, partial, failed oder skipped_overlap; nicht nach skipped_no_credits.
• Mit webhook.events wählen Sie aus; die Kurzformen page und check.completed gehen auch. Eine leere Liste lehnt die API ab (400); lassen Sie events weg, erhalten Sie beide.

{"success": true, "type": "monitor.page", "id": "<checkId>", "webhookId": "…",
 "data": [{"monitorId": "…", "checkId": "…", "url": "https://example.com/preise", "status": "changed",
           "previousScrapeId": "…", "currentScrapeId": "…", "error": null, "isMeaningful": true,
           "judgment": {…}, "diff": {"text": "--- previous\n+++ current\n…", "json": {…}},
           "chunkDiff": {…}, "pageId": "…", "targetId": "…", "statusCode": 200, "metadata": {…}, "createdAt": "…"}],
 "error": null, "metadata": {"projekt": "markt"}}

monitor.check.completed enthält pro Prüfung monitorId, checkId, status, summary, trigger, scheduledFor, startedAt, finishedAt, actualCredits und error; success ist bei partial und failed false.

• Signaturen: Jede Nachricht trägt X-Webhook-Signature (wie unter Webhooks prüfen) und X-Firecrawl-Signature: sha256=<HMAC-SHA256 über die Rohdaten>, beide mit dem Webhook-Schlüssel Ihres Kontos aus dem Dashboard. Prüfen Sie eine davon, bevor Sie die Nachricht verarbeiten.
• Zustellung: Ihr Endpunkt antwortet innerhalb von 10 Sekunden mit einem 2xx-Status. Weiterleitungen folgen wir nicht. Sonst versuchen wir es nach 1, 5 und 15 Minuten erneut, danach gilt die Zustellung als fehlgeschlagen. Die Nachrichten einer Prüfung kommen in ihrer Reihenfolge an. webhookId bleibt bei Wiederholungen gleich; damit erkennen Sie doppelte Zustellungen.
• Größe: Nachrichten über 1 MB verlieren zuerst den Text des Unterschieds, dann diff, chunkDiff und snapshot, zuletzt Details; die Seite trägt dann payloadTruncated: true. Vollständig bleibt die Prüfung über die API.
• Absender: Webhooks kommen nicht von einer festen IP-Adresse. Sichern Sie Ihren Endpunkt über die Signatur und auf Wunsch einen eigenen Header in webhook.headers. Die Adresse muss öffentlich erreichbar sein; wir prüfen sie vor jedem Versuch.
• Ändern Sie die Webhook-Adresse, gehen ausstehende Wiederholungen an die neue. Ist die Überwachung oder ihr Webhook gelöscht, entfallen sie.

import hashlib, hmac

def firecrawl_signature_ok(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

• "notification": {"email": {"enabled": true}} schickt die Meldungen an die E-Mail-Adresse Ihres Kontos. Eine Seite, die dauerhaft nicht lesbar ist, meldet die E-Mail nur beim ersten Mal; Webhooks und die Prüfergebnisse zeigen sie bei jeder Prüfung.
• Mit recipients bestimmen Sie die Empfänger selbst: Ihre Kontoadresse (falls sie dabei sein soll) und bis zu 5 weitere Adressen, sonst 400 TOO_MANY_RECIPIENTS. Jede weitere Adresse erhält einmal eine sachliche Bitte um Bestätigung mit einem Link, der 7 Tage gilt. Erst danach bekommt sie Meldungen; ohne Bestätigung löschen wir sie nach 7 Tagen. Wegwerfadressen sind nicht erlaubt (RECIPIENT_NOT_ALLOWED).
• Den Stand zeigt emailRecipientSubscriptions: pending, confirmed oder unsubscribed, Quelle team (Ihre Kontoadresse) oder opt_in.
• Eine E-Mail kommt nach einer Prüfung mit neuen, geänderten, entfernten oder fehlerhaften Seiten, als Text mit Status, Adresse und der Begründung der KI. Mit includeDiffs stehen Auszüge der Unterschiede dabei (bis 2.000 Zeichen pro Seite, 20.000 pro E-Mail).
• Jede E-Mail enthält einen Link zum Abmelden mit einem Klick (auch als List-Unsubscribe für E-Mail-Programme) und einen Link, mit dem der Empfänger seine Adresse für alle Überwachungen bei Ragfeed sperrt.
• Pro Konto gehen höchstens 50 Meldungs-E-Mails am Tag hinaus, jede Empfängeradresse zählt einzeln. Was mit der E-Mail einer Prüfung geschah, steht in notificationStatus.email.status, etwa sent, suppressed (nichts Wesentliches), no_confirmed_recipients oder account_limit.

Berechnet wird Seite für Seite nach dem Abruf; das Guthaben fällt nie unter null. Reicht es vor einer Prüfung nicht für eine Seite, endet sie als skipped_no_credits. Geht es während einer Prüfung zu Ende, werden die übrigen Seiten als Fehler ohne Kosten gespeichert. Die Überwachung bleibt aktiv und prüft zum nächsten Termin wieder, sobald Credits da sind. Ihre Kontoadresse erhält dazu einmal pro Abrechnungszeitraum einen Hinweis.

Überwachte Seiten zählen über alle aktiven Überwachungen Ihres Kontos: bei einzelnen Seiten jede Adresse, bei einer Website ihr limit, bei einer Suche maxResults. Darüber hinaus: 400 TOO_MANY_WATCHED_URLS. Pro Überwachung höchstens 50 Ziele, pro Konto höchstens 200 Überwachungen. Erlaubt Ihr Plan nach einem Wechsel weniger Seiten, pausiert Ragfeed die neuesten Überwachungen, bis es wieder passt (pausedReason: "plan_limit"), und schreibt Ihnen. Sie bleiben pausiert, bis Sie sie fortsetzen. Ohne aktiven Plan (Abo beendet) laufen keine Überwachungen.

• robots.txt: Überwachungen halten sich an Disallow für RagfeedBot und * sowie an Crawl-delay. Gesperrte Seiten lehnt schon das Anlegen ab (400 ROBOTS_DISALLOWED). Sperrt eine Website später, wird die Seite als Fehler gemeldet und Sie erhalten einmal einen Hinweis. Ist die robots.txt nicht lesbar (Serverfehler, keine Antwort), wird die Seite nicht abgerufen und nicht berechnet.
• Widerspruch: Websites, deren Betreiber widersprochen haben, lassen sich nicht überwachen (403 SITE_OPTED_OUT).
• Profilseiten: Profilseiten sozialer Netzwerke sind ausgeschlossen (400 URL_NOT_ALLOWED_FOR_MONITORING, siehe Nutzungsregeln); Suchziele filtern sie aus den Treffern. Gesperrt sind: linkedin.com/in/, linkedin.com/pub/, instagram.com/, facebook.com/, fb.com/, tiktok.com/@, x.com/, twitter.com/, xing.com/profile/, threads.net/@, bsky.app/profile/ (auch mit Subdomain wie www. oder m.).
• Weiterleitungen: Leitet eine Seite auf eine andere Adresse weiter, gelten diese Regeln auch für das Ziel. Verbietet die robots.txt des Ziels den Abruf, hat sein Betreiber widersprochen oder ist es eine Profilseite, wird die Seite als Fehler gemeldet und nicht berechnet.
• Keine Zugangsdaten: Überwachungen speichern ihre Optionen dauerhaft. Header, deren Name nach Anmeldung aussieht (auth, cookie, token, key, secret, session, password, passwd, credential), lehnt die API ab (SENSITIVE_HEADER_NOT_ALLOWED), ebenso actions (ACTIONS_NOT_SUPPORTED_FOR_MONITORS) und zeroDataRetention (ZERO_DATA_RETENTION_NOT_SUPPORTED), weil eine Überwachung den letzten Stand speichern muss. Adressen mit Name und Passwort (https://name:passwort@…) lehnt sie ebenso ab (CREDENTIALS_IN_URL_NOT_ALLOWED), auch als Webhook-Adresse. Die Header Ihres Webhooks gelten Ihrem eigenen Endpunkt; sie werden gespeichert und nur als *** angezeigt.

Prüfungen mit ihren Seiten und Unterschieden löscht Ragfeed nach retentionDays: Standard 30 Tage, wählbar 1 bis 90 (mehr ergibt 400 RETENTION_TOO_LONG). Den letzten Stand jeder Seite, mit dem verglichen wird, behalten wir, solange die Überwachung besteht; ist sie länger als 90 Tage pausiert, löschen wir ihn, und die nächste Prüfung meldet die Seiten als neu. Protokolle der Webhook- und E-Mail-Zustellung bleiben 30 Tage. Mit dem Löschen der Überwachung ist alles weg; Details stehen in der Datenschutzerklärung.

# pip install firecrawl-py
from firecrawl import Firecrawl

app = Firecrawl(api_key="sk-...", api_url="https://api.ragfeed.de")

monitor = app.create_monitor(
    name="Preisseite",
    schedule={"text": "daily at 7:00", "timezone": "Europe/Berlin"},
    targets=[{"type": "scrape", "urls": ["https://example.com/"]}],
    goal="Preisänderungen und neue Tarife sind wichtig, Layout und Tippfehler nicht.",
    notification={"email": {"enabled": True, "includeDiffs": True}},
    retention_days=60,
)
print(monitor.id, monitor.next_run_at, monitor.estimated_credits_per_month)

check = app.run_monitor(monitor.id)   # sofort prüfen, außerhalb des Zeitplans
# … wenn die Prüfung fertig ist (Webhook monitor.check.completed oder ein paar Sekunden später):
for c in app.list_monitor_checks(monitor.id, limit=5):
    print(c.status, c.summary.changed, c.actual_credits)

detail = app.get_monitor_check(monitor.id, check.id)
for page in detail.pages:
    print(page.status, page.url, page.judgment.reason if page.judgment else "")

app.update_monitor(monitor.id, status="paused")   # "active" setzt fort
app.delete_monitor(monitor.id)

Das Node.js-SDK ruft dieselben Endpunkte auf (createMonitor, runMonitor, getMonitorCheck …). Das Python-SDK lässt Felder mit None weg; um webhook, notification oder goal zu entfernen, schicken Sie null per HTTP.

Nur bei Ragfeed (die SDKs ignorieren unbekannte Felder): POST /v2/monitor/estimate, für eine Änderung mit ?monitorId=… (die Seiten dieser Überwachung zählen dann nicht doppelt; bei einer pausierten sagt resumeBlocked, warum sie sich so nicht fortsetzen ließe); an der Überwachung creditsPerCheck, checksPerMonth, estimatedCreditsPerMonthWithoutJudge, watchedUrls und pausedReason; an jeder Seite chunkDiff und isMeaningful; die Angaben in targetResults und webhookDeliveries an jeder Prüfung; deutsche Zeitplan-Texte; die zusätzliche Signatur X-Webhook-Signature.

Anders als bei Firecrawl: Unveränderte Seiten senden keinen Webhook, entfernte Seiten schon. Prüfergebnisse bleiben höchstens 90 Tage. E-Mails gehen an Ihre Kontoadresse und bis zu 5 weitere bestätigte Adressen. Der kürzeste Prüfabstand hängt vom Plan ab. Browser-Aktionen und Slack gibt es in der Beta nicht, Suchziele durchsuchen das Web.

Prüft Ihre Firewall verschlüsselte Verbindungen (TLS-Inspektion), braucht Ihr Programm das Zertifikat Ihrer Firma:

# Bash – Python (requests und httpx; firecrawl-py nutzt beide, also beide setzen)
export REQUESTS_CA_BUNDLE=/pfad/zu/ca-paket.pem
export SSL_CERT_FILE=/pfad/zu/ca-paket.pem
# Bash – Node.js (wird beim Programmstart gelesen)
export NODE_EXTRA_CA_CERTS=/pfad/zu/firmen-ca.pem

# PowerShell (Windows)
$env:REQUESTS_CA_BUNDLE="C:\pfad\ca-paket.pem"
$env:SSL_CERT_FILE="C:\pfad\ca-paket.pem"
$env:NODE_EXTRA_CA_CERTS="C:\pfad\firmen-ca.pem"

REQUESTS_CA_BUNDLE und SSL_CERT_FILE ersetzen die mitgelieferten Zertifikate: Die Datei muss also auch die öffentlichen Zertifizierungsstellen enthalten (Firmenzertifikat angehängt). NODE_EXTRA_CA_CERTS ergänzt nur, dort genügt das Firmenzertifikat.