API-Dokumentation

Basis-URL: https://api.ragfeed.de. Authentifizierung per Header Authorization: Bearer <API-Key>. Die interaktive Referenz aller Felder finden Sie unter /docs.

Inhalt: Endpunkte · Umstieg von Firecrawl · Scrape · KI-Formate · Crawl · Webhooks · Dokumente · Batch, Map, Search, Extract · Fehlercodes

Endpunkte auf einen Blick

Ragfeed versteht die Firecrawl-API in Version 1 und 2.

Umstieg von Firecrawl

Die API ist kompatibel zu den Open-Source-SDKs firecrawl-py (Python) und @mendable/firecrawl-js (Node.js) sowie zu Integrationen wie LangChain. Setzen Sie nur api_url bzw. apiUrl auf https://api.ragfeed.de und verwenden Sie Ihren Ragfeed-Key. Der restliche Code bleibt gleich.

# pip install firecrawl-py
from firecrawl import Firecrawl

app = Firecrawl(
    api_key="sk-...",
    api_url="https://api.ragfeed.de",   # ← die einzige Änderung
)
doc = app.scrape("https://example.com", formats=["markdown"])
print(doc.markdown)

// npm i @mendable/firecrawl-js
import Firecrawl from "@mendable/firecrawl-js";

const app = new Firecrawl({ apiKey: "sk-...", apiUrl: "https://api.ragfeed.de" });
const doc = await app.scrape("https://example.com", { formats: ["markdown"] });
console.log(doc.markdown);

curl -X POST https://api.ragfeed.de/v2/scrape \
  -H "Authorization: Bearer sk-..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "formats": ["markdown"]}'

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.

Formate für KI-Anwendungen (nur bei Ragfeed)

Zwei zusätzliche Formate liefern die Seite so, wie Sprachmodelle und Vektordatenbanken sie am besten verarbeiten. Sie kosten keine zusätzlichen Credits. Warum das Tokens spart und Antworten verbessert: KI-gerechte Daten.

{
  "url": "https://example.com/leitfaden",
  "formats": ["llmMarkdown", {"type": "chunks", "maxTokens": 500}]
}

• llmMarkdown: Markdown mit einem Kopf aus Titel, Adresse, Sprache, Abrufzeit und Tokenzahl. Linkziele stehen als nummerierte Liste am Ende, Bilder nur als Alternativtext. So bleibt der Text flüssig lesbar und spart Tokens.
• chunks: die Seite entlang ihrer Überschriften in Abschnitte zerlegt, jeweils mit heading (Überschriftenpfad, z. B. „Leitfaden › Schritt 2“), text, tokens, hash und url. maxTokens liegt zwischen 100 und 4.000 (Standard 500). Über den hash erkennen Sie geänderte Abschnitte und müssen nur diese neu einbetten. Tokenzahlen sind vorsichtige Schätzungen (3,5 Zeichen pro Token), meist etwas über dem, was Ihr Modell zählt. Ein Rest am Ende eines langen Abschnitts wird dem vorigen Chunk angehängt, der dadurch bis zu 20 % über maxTokens liegen kann. Kurze Teaser, etwa auf Startseiten, werden zu einem Chunk zusammengefasst.

Die offiziellen Firecrawl-SDKs kennen diese beiden Formate nicht und lehnen sie teils vor dem Senden ab. Nutzen Sie dafür direkt HTTP (siehe cURL-Beispiel).

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://ihr-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 Ihrem Webhook-Schlüssel aus dem Dashboard. Verwerfen Sie 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 "file=@vertrag.pdf" \
  -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.