Scan starten
Legt einen neuen Scan-Lauf an und gibt ihn samt Kennung zurück. Die Antwort kommt sofort; der Lauf selbst wird eingereiht.
Aktive Läufe (active: true) setzen eine verifizierte Domain voraus, sonst
antwortet die API mit 403 domain_not_verified. Starten dürfen Schlüssel mit
den Rechten start_scans und full.
Anfrage
https://api.red-check.de/v1/scans
Anfrage
curl -X POST https://api.red-check.de/v1/scans \
-H "Authorization: Bearer rc_live_••••••••" \
-H "Content-Type: application/json" \
-d '{
"domain_id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
"active": false,
"security": true,
"privacy": false,
"accessibility": false,
"full_site": false,
"context": "shop"
}'Felder
FeldTypBeschreibung
domain_id
uuidPflicht
–
active
boolean
Aktive Prüfungen (Portscan, TLS, Templates, Rate-Limit, WAF, XSS, SQLi).
backend_scope_policy
enum
Version der ausdrücklich bestätigten Backend-Beauftragung. 0 bedeutet keine Erweiterung. Mit 1 bestätigt der Auftraggeber, dass die aktive Prüfung gezielte anonyme Leseprüfungen nachweislich verwendeter, eindeutig zugeordneter App-Backends umfasst. Die API genehmigt jedes Backendprojekt einzeln; fremde Projekte, private Zugangsdaten und schreibende Aktionen sind nicht umfasst. Nur aktive Sicherheitsjobs der Generation 2 ohne unterschriebenes Manifest wenden Version 1 an. Passive und signierte Aufträge sowie ältere Generationen bleiben bei 0.
security
boolean
Modul Sicherheit: DNS, TLS, Kopfzeilen, Softwarestand, CVE, offene Pfade. `active` ist die Eingriffstiefe genau dieses Moduls und ohne `security` nicht wählbar (400 `validation_failed`). Mindestens ein Modul muss an sein, sonst ebenfalls 400.
privacy
boolean
Modul Datenschutz (DSGVO/TDDDG) im echten Browser. Immer passiv. Ab Pro. Die Vorgabe hängt deshalb an Plan und Abrechnung: an bei Abrechnung nach Kontingent ab Pro, aus bei Abrechnung je Lauf (Agentur) und in Free. Ausdrücklich `true` in Free ergibt `plan_upgrade_required` (402). Ein fester `default` wäre hier für einen der Pläne falsch.
accessibility
boolean
Modul Barrierefreiheit (WCAG 2.2 AA, BITV 2.0, BFSG). Immer passiv und ohne Eigentumsnachweis nutzbar, da es gewöhnliche Seitenaufrufe sind. Ab Pro; `true` in Free ergibt `plan_upgrade_required` (402).
full_site
boolean
Vollprüfung: alle vom Seitenfinder gefundenen Unterseiten statt Startseite und Stichprobe. Deutlich längere Laufzeit.
path_prefix
string
Teilscan: Die Seitenerhebung bleibt auf dieses Unterverzeichnis begrenzt, etwa `/shop`. Leer oder `/` bedeutet die ganze Domain. Erlaubt ist nur ein Pfad: Er beginnt mit `/` und enthält weder Query (`?`) noch Fragment (`#`), kein Segment `..`, keine leeren Segmente und keinen Leerraum. Gespeichert wird er ohne Schrägstrich am Ende (`/shop/` wird `/shop`); Groß- und Kleinschreibung bleiben erhalten. Die Startseite `/` wird trotzdem geholt, weil Kopfzeilen, TLS und die domainweiten Prüfungen an ihr hängen. Nur für die Sicherheitsprüfung und ab dem Plan Pro. Mit `privacy` oder `accessibility` bleibt es bei der Vollprüfung des ganzen Auftritts, und ein Präfix wird mit `400 validation_failed` abgewiesen, in Free mit `402 plan_upgrade_required`. Ein Teilscan ist eine Vollprüfung (`full_site` gilt als `true`) und zählt wie jeder andere Lauf gegen das Kontingent. Nur die Sicherheitsprüfung hat hier die Wahl. Datenschutz und Barrierefreiheit laufen immer über alle Unterseiten, weil ihre Aussage dem ganzen Auftritt gilt und das BFSG keine Stichprobe kennt. Ist `privacy` oder `accessibility` gesetzt, gilt `true`, auch wenn dieses Feld fehlt oder `false` trägt. Abgewiesen wird dafür nichts: Der Lauf trägt den geltenden Wert, und die Antwort nennt ihn.
context
enum | null
Übersteuert den Kontext der Domain für diesen Lauf.
cve_include_possible
boolean
Auch „mögliche“, rein versionsbasierte CVE in den Bericht aufnehmen.
nuclei_full
boolean
Voller Template-Katalog statt der auf erkannte Technik gescopten Auswahl. Deutlich langsamer.
make_pdf
boolean
–
checks
string[]
Gezielte Checks aus dem Check-Katalog (`check_katalog.check_id`), die dieser Lauf zusätzlich auswertet und je Eintrag ein Verdikt in `check_results` ablegt. Jede Kennung muss im Katalog stehen, sonst `400 validation_failed`. Ein aktiver Nachweis gilt nur, wenn der Lauf ohnehin aktiv ist und die Domain einen Eigentumsnachweis trägt; sonst bleibt das Verdikt versionsbasiert. Leer bedeutet kein gezielter Check.
auth_cookie
string | null
Für die authentifizierte Prüfung des eingeloggten Bereichs. Verschlüsselt gespeichert, nie in Logs oder Berichten. Nur für eine Domain mit gültigem Eigentumsnachweis oder einen Lauf, den eine Agentur-Beauftragung trägt (`authorization`, auch bei einem passiven Lauf). Sonst `403 domain_not_verified`: mit Anmeldedaten kommt der Scanner hinter eine Zugangssicherung, und das darf nur, wer über die Website verfügen darf (§ 202a StGB).
auth_header
string | null
Wie `auth_cookie`, als Header-Zeile.
authorization
object | null
Pflicht, wenn `active` gesetzt ist, die Domain keinen gültigen Eigentumsnachweis hat und die Organisation eine Agentur ist. Sonst wird der Lauf mit `domain_not_verified` abgewiesen. Bei einem passiven Lauf wird das Feld ignoriert, weil passive Prüfungen keine Beauftragung brauchen; ausser er trägt `auth_cookie` oder `auth_header` (seit 1.9.0), dann gilt dieselbe Pflicht wie für einen aktiven Lauf.
Antwort
Antwort
{
"id": "3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e",
"domain": "",
"tier": "passive",
"status": "queued",
"progress": 0,
"context": "shop",
"created_at": "2026-09-03T09:14:22Z"
}Merken Sie sich id. Fortschritt, Befunde und Artefakte hängen daran.
Fehlercodes
202
Eingereiht.
400
Eingabe ungültig (`validation_failed`).
402
Kontingent erschöpft (`quota_exceeded`). `plan_upgrade_required` bei einer Stufe, die für diese Organisation nicht freigeschaltet ist (Grenze null), bei einem Prüfbereich, den der Plan nicht enthält (`details.module` nennt den ersten gesperrten Bereich, `details.modules` alle, aus `privacy` und `accessibility`), und bei einer Vollprüfung im Plan Free (`details.field = "full_site"`). Bei Abrechnung je Lauf (Agentur) außerdem `price_not_set`, wenn für ein Paket des Laufs kein Preis hinterlegt ist; `details.packages` nennt die Pakete ohne Preis (aus `passive`, `active`, `privacy`, `accessibility`). Seit 1.12.0 in einem Kundenkonto einer Agentur: `quota_exceeded`, sobald ein Paket des Laufs im Kalendermonat ausgeschöpft ist. Abgewiesen wird dann der ganze Lauf, auch wenn die übrigen Pakete noch Platz hätten. `details.reason = "period_limit"`, `details.package` nennt das erste volle Paket (aus `passive`, `active`, `privacy`, `accessibility`), `details.limit` und `details.used` die Zahlen dazu, `details.period_end` das Ende des Monats. Eine Grenze von 0 heißt: das Paket ist nicht freigegeben, ebenfalls `quota_exceeded`.
403
Domain nicht verifiziert (`domain_not_verified`), Organisation gedrosselt (`organization_throttled`) oder gesperrt (`organization_blocked`), oder der API-Schlüssel darf keine Scans starten (`api_key_scope_insufficient`). Seit 1.9.0 auch `domain_not_verified` mit `details.missing = "verification"`, wenn `auth_cookie` oder `auth_header` gesetzt ist und die Domain weder einen gültigen Eigentumsnachweis hat noch der Lauf eine tragende Beauftragung einer Agentur mitbringt. Das gilt für jede Stufe, auch passiv, und für jeden Weg (Sitzung, API-Schlüssel, MCP, Wiederholung).
429
Zu viele Anfragen (`rate_limited`).
Bei Abrechnung je Lauf (Plan Agentur) kommt 402 price_not_set, wenn für ein
Paket des Laufs noch kein Preis vereinbart ist. Mehr dazu unter
Nutzung und Abrechnung. Alle Codes mit
Status stehen unter Konventionen.
Beispiel: Polling
Ein Lauf ist typischerweise nach zwei bis vier Minuten fertig, mit aktiven Prüfungen nach zehn bis zwanzig. Fragen Sie höchstens alle fünf Sekunden nach. Für Live-Fortschritt gibt es den Ereignisstrom. Webhooks gibt es nicht.
Warten, bis der Lauf fertig ist
#!/usr/bin/env bash
set -euo pipefail
KEY="rc_live_••••••••"
SCAN=$(curl -sS -X POST https://api.red-check.de/v1/scans \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"domain_id":"3f9a1c20-5e4b-4d8a-9a11-0c21e7b4c21e","active":true}' \
| jq -r .id)
while :; do
state=$(curl -sS "https://api.red-check.de/v1/scans/$SCAN" \
-H "Authorization: Bearer $KEY" | jq -r '.status + " " + (.progress|tostring)')
echo "$state"
case "$state" in
done*|failed*|canceled*) break ;;
esac
sleep 5
done