API-DOKUMENTATION

WebPrüfer REST-API

87 automatisierte Prüfungen in 8Kategorien — dieselbe Engine wie web-pruefer.de, per API. Ein Request, ein strukturierter JSON-Report. Für Unternehmen, die nicht eine, sondern viele Websites prüfen: Kanzleien für ihre Mandanten, Agenturen für ihre Kunden, Hoster im eigenen Tarif.

Testzugang anfragen Zu den Endpunkten

Testzugang auf Anfrage — keine Selbstregistrierung, keine Kreditkarte. API-Schlüssel werden von uns manuell ausgestellt.

Authentifizierung

Jeder Request an einen /api/v1/*-Endpunkt benötigt einen Bearer-Token im Authorization-Header:

Authorization: Bearer wp_live_<32-stelliger-Schlüssel>

Es gibt keine Selbstregistrierung. Testzugang erhalten Sie auf Anfrage über das Zugangsformular — wir stellen den ersten Schlüssel manuell aus. Fehlt oder stimmt der Header nicht, antwortet die API mit 401 (auth_required bzw. invalid_key).

Endpunkte

Scans

POST/api/v1/scan

Startet einen synchronen Einzelseiten-Scan (Antwortzeit bis zu 45 Sekunden, danach 504 scan_timeout). Prüft URL-Format und blockt private/interne Adressen (SSRF-Schutz). Maximale URL-Länge: 2048 Zeichen. Zählt gegen das monatliche Scan-Kontingent und das Rate-Limit pro Minute.

Request Body

{ "url": "https://example.de" }

Response 200

{
  "id": "cm4x7k2a00001",
  "url": "https://example.de",
  "score": 72,
  "scannedAt": "2026-07-18T10:15:00.000Z",
  "checksTotal": 87,
  "checksPassed": 58,
  "checksFailed": 21,
  "checksWarning": 8,
  "checks": [
    {
      "id": "ssl",
      "label": "SSL-Verschlüsselung",
      "status": "pass",
      "details": "Die Website verwendet HTTPS.",
      "group": "security"
    },
    {
      "id": "impressum_exists",
      "label": "Impressum vorhanden",
      "status": "fail",
      "details": "Kein Impressum gefunden.",
      "group": "legal",
      "fix": "Impressum-Seite gemäß §5 TMG ergänzen."
    }
  ]
}

Fehler: 400 invalid_request / invalid_url · 401 auth_required / invalid_key · 429 rate_limited / quota_exceeded · 500 scan_error · 504 scan_timeout

GET/api/v1/scan/:id

Ruft ein bereits abgeschlossenes Scan-Ergebnis anhand seiner ID ab. Liefert nur Scans, die zu Ihrem eigenen Account gehören. Nicht rate-limitiert.

Response 200

{
  "id": "cm4x7k2a00001",
  "url": "https://example.de",
  "score": 72,
  "mode": "single",
  "status": "completed",
  "scannedAt": "2026-07-18T10:15:00.000Z",
  "checksTotal": 87,
  "checksPassed": 58,
  "checksFailed": 21,
  "checksWarning": 8,
  "checks": [ /* ... */ ]
}

Fehler: 400wrong_endpoint (ID gehört zu einem Site-Audit — nutzen Sie dann /api/v1/site-audit/:id) · 401 auth_required / invalid_key · 404 not_found

Site-Audits

POST/api/v1/site-audit

Startet einen asynchronen Mehrseiten-Audit: Crawler durchsucht bis zu 20 Unterseiten, führt Einzel-Checks, PageSpeed-Analyse und seitenübergreifende Prüfungen durch. Der Request antwortet sofort mit 202 — das eigentliche Audit läuft im Hintergrund. Zählt gegen das monatliche Audit-Kontingent.

Request Body

{ "url": "https://example.de" }

Response 202

{
  "id": "aB3cD9eF2gH1",
  "url": "https://example.de",
  "status": "processing",
  "statusUrl": "/api/v1/site-audit/aB3cD9eF2gH1/status",
  "resultUrl": "/api/v1/site-audit/aB3cD9eF2gH1"
}

Fehler: 400 invalid_request / invalid_url · 401 auth_required / invalid_key · 429 rate_limited / quota_exceeded

GET/api/v1/site-audit/:id

Liefert das vollständige Audit-Ergebnis, sobald es fertig ist. Solange das Audit noch läuft, antwortet der Endpunkt weiterhin mit 202. Nicht rate-limitiert.

Response 200 (abgeschlossen)

{
  "id": "aB3cD9eF2gH1",
  "url": "https://example.de",
  "score": 68,
  "status": "completed",
  "scannedAt": "2026-07-18T10:15:00.000Z",
  "mode": "site-audit",
  "pages": [
    { "url": "https://example.de", "statusCode": 200, "score": 74 },
    { "url": "https://example.de/impressum", "statusCode": 200, "score": 60 }
  ],
  "aggregatedChecks": [
    {
      "id": "impressum_exists",
      "label": "Impressum vorhanden",
      "group": "legal",
      "overallStatus": "fail",
      "priority": "Hoch",
      "affectedPages": [ { "url": "https://example.de/kontakt", "status": "fail" } ]
    }
  ],
  "pageSpeed": { "mobile": { "strategy": "mobile", "score": 71, "metrics": [] } },
  "partial": false,
  "checks": [ /* ... */ ]
}

Response 202 (noch in Bearbeitung): { "id", "status": "processing", "message" }

Fehler: 401 auth_required / invalid_key · 404 not_found · 422 audit_failed (Website nicht erreichbar oder blockiert)

GET/api/v1/site-audit/:id/status

Leichtgewichtiger Polling-Endpunkt für den Fortschritt eines laufenden Audits. Empfohlen: alle 2–5 Sekunden abfragen, bis status auf completed oder failed wechselt. Nicht rate-limitiert.

Response 200

{
  "id": "aB3cD9eF2gH1",
  "status": "processing",
  "progress": {
    "phase": "crawling",
    "pagesFound": 14,
    "pagesScanned": 6,
    "currentUrl": "https://example.de/kontakt"
  }
}

Fehler: 401 auth_required / invalid_key · 404 not_found

API-Schlüssel

GET/api/v1/keys

Listet alle aktiven (nicht widerrufenen) Schlüssel Ihres Accounts. Zeigt nur den Prefix, nie den vollständigen Schlüssel.

Response 200

{
  "keys": [
    {
      "id": "ck_1a2b3c",
      "keyPrefix": "wp_live_a1b2",
      "name": "Production Server",
      "lastUsedAt": "2026-07-17T08:02:11.000Z",
      "createdAt": "2026-06-01T09:00:00.000Z"
    }
  ]
}

Fehler: 401 auth_required / invalid_key

POST/api/v1/keys

Erstellt einen neuen Schlüssel für Ihren Account (maximal 10 aktive Schlüssel gleichzeitig). Der vollständige Schlüssel wird nur in dieser einen Antwort angezeigt — danach ist nur noch der Prefix sichtbar.

Request Body (optional)

{ "name": "Production Server" }

Response 201

{
  "id": "ck_1a2b3c",
  "key": "wp_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
  "keyPrefix": "wp_live_a1b2",
  "name": "Production Server",
  "createdAt": "2026-07-18T09:00:00.000Z",
  "warning": "Save this key — it will not be shown again."
}

Fehler: 400 key_limit_exceeded · 401 auth_required / invalid_key

DELETE/api/v1/keys/:id

Widerruft einen Schlüssel dauerhaft. Der Schlüssel, mit dem der Request selbst authentifiziert wurde, kann nicht widerrufen werden (Schutz gegen versehentliche Selbstaussperrung).

Response

204 No Content

Fehler: 400 cannot_revoke_active_key · 401 auth_required / invalid_key · 404 not_found · 409 already_revoked

Rate-Limits & Kontingente

POST /scan und POST /site-audit liefern bei jedem Request drei Header mit dem aktuellen Rate-Limit-Status. Lesende GET-Endpunkte sind nicht rate-limitiert.

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 1710748800

X-RateLimit-Reset ist ein Unix-Timestamp (Sekunden), wann das aktuelle 1-Minuten-Fenster zurückgesetzt wird. Zusätzlich gibt es ein monatliches Kontingent für Scans und Audits, das je nach Plan variiert.

Plan-Stufen

Plan	Scans / Monat	Audits / Monat	Requests / Min
Starter	100	10	10
Pro	500	50	30
Enterprise	Unbegrenzt	Unbegrenzt	60

Konditionen individuell nach Volumen — starten Sie mit einem kostenlosen Pilot. Kein Preis auf dieser Seite: Zugang und Plan werden persönlich abgestimmt.

Fehlerformat

Alle Fehlerantworten folgen demselben Schema:

{
  "error": "Menschenlesbare Fehlermeldung",
  "code": "maschinenlesbarer_code"
}

code	HTTP-Status	Bedeutung
auth_required	401	Authorization-Header fehlt.
invalid_key	401	Schlüssel hat falsches Format oder ist ungültig/widerrufen.
rate_limited	429	Zu viele Requests pro Minute (Plan-Limit erreicht).
quota_exceeded	429	Monatliches Scan- oder Audit-Kontingent aufgebraucht.
invalid_request	400	Pflichtfeld fehlt, JSON ungültig oder URL zu lang (max. 2048 Zeichen).
invalid_url	400	URL ist kein gültiges https://-Ziel (SSRF-Schutz greift z. B. bei privaten IPs).
scan_timeout	504	Scan hat das 45-Sekunden-Limit überschritten.
scan_error	500	Scan ist unerwartet fehlgeschlagen.
not_found	404	Ressource existiert nicht oder gehört nicht zu Ihrem Account.
wrong_endpoint	400	Scan-ID gehört zu einem Site-Audit — falscher Endpunkt verwendet.
audit_failed	422	Site-Audit fehlgeschlagen (Website nicht erreichbar oder blockiert).
key_limit_exceeded	400	Maximal 10 aktive Schlüssel pro Account erreicht.
already_revoked	409	Schlüssel wurde bereits widerrufen.
cannot_revoke_active_key	400	Der Schlüssel, mit dem der Request authentifiziert wurde, kann nicht sich selbst widerrufen.

Integrationsbeispiel

curl

curl -X POST https://web-pruefer.de/api/v1/scan \
  -H "Authorization: Bearer wp_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.de"}'

Node.js (native fetch, Node 18+)

const API_BASE = "https://web-pruefer.de";
const headers = {
  Authorization: `Bearer ${process.env.API_KEY}`,
  "Content-Type": "application/json",
};

// Einzelseiten-Scan (synchron)
async function quickScan(url) {
  const res = await fetch(`${API_BASE}/api/v1/scan`, {
    method: "POST",
    headers,
    body: JSON.stringify({ url }),
  });
  if (!res.ok) {
    const err = await res.json();
    throw new Error(`Scan failed (${res.status}): ${err.error} [${err.code}]`);
  }
  return res.json();
}

// Site-Audit (asynchron, mit Polling)
async function siteAudit(url) {
  const start = await fetch(`${API_BASE}/api/v1/site-audit`, {
    method: "POST",
    headers,
    body: JSON.stringify({ url }),
  });
  const { id, statusUrl } = await start.json();

  let status = "processing";
  while (status === "processing") {
    await new Promise((r) => setTimeout(r, 3000));
    const s = await fetch(`${API_BASE}${statusUrl}`, { headers });
    status = (await s.json()).status;
  }

  const result = await fetch(`${API_BASE}/api/v1/site-audit/${id}`, { headers });
  return result.json();
}

Ein vollständigeres Beispiel inklusive Fehlerbehandlung finden Sie in unserem Repository unter docs/examples/nodejs-integration.ts.

Häufige Fragen zur API

Hat WebPrüfer eine API?

Ja. Die WebPrüfer REST-API bietet dieselben automatisierten Prüfungen wie der Web-Scanner — programmatisch ansteuerbar für Unternehmen, die nicht eine, sondern viele Websites prüfen wollen (Kanzleien, Agenturen, Hoster, Compliance-Beratungen).

Welche Prüfungen deckt die API ab?

87 Prüfungen in 8 Kategorien — u. a. DSGVO, Impressum, Cookies, SSL und Barrierefreiheit (BFSG). Jeder Request liefert einen strukturierten JSON-Report mit Score, Einzelergebnissen je Prüfung und Handlungsempfehlungen.

Wie erhalte ich einen API-Schlüssel?

Es gibt keine Selbstregistrierung. Testzugang wird auf Anfrage über das Zugangsformular vergeben — wir stellen den ersten Schlüssel manuell aus, in der Regel innerhalb von 24 Stunden.

Was kostet die API?

Konditionen individuell nach Volumen, Start mit kostenlosem Pilot.

Keine Rechtsberatung

WebPrüfer ist ein automatisiertes Analyse-Tool. Ergebnisse zeigen, was gefunden wurde und was möglicherweise angepasst werden sollte — sie stellen keine Rechtsberatung dar und ersetzen keine anwaltliche Prüfung. Bei SPA-/React-Websites ohne Server-Side-Rendering kann der automatische Check Inhalte, die erst per JavaScript geladen werden, möglicherweise nicht vollständig erfassen.

Testzugang für Ihr Unternehmen anfragen

Kostenloser Pilot, individuelle Konditionen nach Volumen.

Zugang anfragen →

Kanzlei oder Agentur ohne eigene Entwicklung? Partnerprogramm ansehen →