API-Dokumentation

Basis-URL: https://api.ragfeed.de. Authentifizierung per Header Authorization: Bearer <API-Key>. Die vollständige, interaktive Referenz aller Felder findest du unter /docs.

SDKs

Die API ist kompatibel zu den Open-Source-SDKs firecrawl-py (Python) und @mendable/firecrawl-js (Node.js). Setze nur api_url bzw. apiUrl auf https://api.ragfeed.de.

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

Scrape – eine Seite

POST /v2/scrape
{
  "url": "https://example.com/produkt",
  "formats": ["markdown", "links", {"type": "screenshot", "fullPage": true}],
  "onlyMainContent": true,          // Navigation, Footer, Cookie-Banner entfernen
  "waitFor": 1000,                  // ms warten (erzwingt Browser-Rendering)
  "location": {"country": "DE"},    // Sprache/Accept-Language
  "maxAge": 172800000               // Cache-Treffer bis 2 Tage alt sind ok
}

Formate: markdown, html, rawHtml, rawBase64, links, images, screenshot, summary, changeTracking sowie die KI-Formate {"type":"json","schema":{…},"prompt":"…"}, {"type":"question","question":"…"}, {"type":"highlights","query":"…"}, product und menu.

Browser-Aktionen

"actions": [
  {"type": "click", "selector": "#suche"},
  {"type": "write", "text": "Laptop"},
  {"type": "press", "key": "Enter"},
  {"type": "wait", "selector": ".ergebnisse"},
  {"type": "scroll", "direction": "down"},
  {"type": "screenshot", "fullPage": true},
  {"type": "executeJavascript", "script": "return document.title"}
]

Crawl – ganze Website

POST /v2/crawl
{
  "url": "https://docs.example.com",
  "limit": 500,
  "includePaths": ["^/guides/.*"],
  "excludePaths": ["^/guides/archiv/.*"],
  "maxDiscoveryDepth": 3,
  "sitemap": "include",             // include | skip | only
  "scrapeOptions": {"formats": ["markdown"]},
  "webhook": {"url": "https://dein-server.de/hook", "events": ["page", "completed"]}
}
→ {"success": true, "id": "…", "url": "https://api.ragfeed.de/v2/crawl/…"}

GET /v2/crawl/{id}          Status und Ergebnisse (seitenweise über "next")
GET /v2/crawl/{id}/errors   fehlgeschlagene und per robots.txt gesperrte URLs
DELETE /v2/crawl/{id}       abbrechen

Ohne crawlEntireDomain werden nur Unterseiten der Start-URL gecrawlt. Mit "prompt": "nur der Blog" erzeugt die KI passende Filter.

Webhooks prüfen

Jede Webhook-Nachricht enthält den Header X-Webhook-Signature: t=<Zeit>,v1=<Signatur>. Die Signatur ist ein HMAC-SHA256 über <Zeit>.<Rohdaten> mit deinem Webhook-Schlüssel aus dem Dashboard. Verwirf Nachrichten, deren Signatur nicht passt oder deren Zeitstempel älter als 5 Minuten ist.

import hashlib, hmac, time

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) < 300

Dokumente einlesen

Datei hochladen (PDF inkl. gescannter Seiten, .docx, .xlsx, .xls, .pptx, .odt, .ods, .odp, .epub, .csv, .html) – oder einfach einen Link auf ein Dokument an /v2/scrape schicken.

curl -X POST https://api.ragfeed.de/v2/parse \
  -H "Authorization: Bearer sk-..." \
  -F "[email protected]" \
  -F 'options={"formats": ["markdown"], "parsers": [{"type": "pdf", "mode": "auto"}]}'

# Python (firecrawl-py)
doc = app.parse("vertrag.pdf")

PDF-Modi: fast (nur Textebene), auto (Texterkennung für Seiten ohne Text, Standard), ocr (Texterkennung für jede Seite). Alte Binärformate (.doc, .ppt, .rtf) werden nicht unterstützt.

Batch-Scrape – viele URLs

POST /v2/batch/scrape
{"urls": ["https://a.de", "https://b.de"], "formats": ["markdown"]}
GET  /v2/batch/scrape/{id}

Map – alle URLs einer Domain

POST /v2/map
{"url": "https://example.com", "search": "preise", "limit": 1000}
→ {"success": true, "links": [{"url": "…", "title": "…"}]}

Search – Websuche

POST /v2/search
{"query": "beste Vektordatenbank 2026", "limit": 5, "sources": ["web", "news"],
 "tbs": "qdr:m", "scrapeOptions": {"formats": ["markdown"]}}

Extract – strukturierte Daten über mehrere Seiten

POST /v2/extract
{
  "urls": ["https://example.com/team/*"],
  "prompt": "Alle Teammitglieder mit Rolle",
  "schema": {"type": "object", "properties": {"people": {"type": "array", "items": {
      "type": "object", "properties": {"name": {"type": "string"}, "role": {"type": "string"}}}}}}
}
GET /v2/extract/{id}

Konto

GET /v2/team/credit-usage              verbleibende Credits
GET /v2/team/credit-usage/historical   Verbrauch pro Monat
GET /v2/team/queue-status              laufende Aufträge

Fehlercodes

Alle Fehler haben die Form {"success": false, "error": "…", "code": "…"}. Die älteren /v1/*-Endpunkte werden ebenfalls unterstützt.