Zum Inhalt springen
RedcheckStartseite
REST-API / Scan starten

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.

Anfrage

POSThttps://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,
  "privacy": true,
  "context": "shop",
  "make_pdf": true
}'

Felder

domain_id
uuidPflicht
—
active
boolean
Aktive Prüfungen (Portscan, TLS, Templates, Rate-Limit, WAF, XSS, SQLi).Vorgabe false
privacy
boolean
Datenschutz-Prüfung im echten Browser. Modul quer zur Stufe.Vorgabe true
context
enum | null
Übersteuert den Kontext der Domain für diesen Lauf.shop · brochure · saas · internal
cve_include_possible
boolean
Auch „mögliche“, rein versionsbasierte CVE in den Bericht aufnehmen.Vorgabe false
nuclei_full
boolean
Voller Template-Katalog statt der auf erkannte Technik gescopten Auswahl. Deutlich langsamer.Vorgabe false
make_pdf
boolean
—Vorgabe true
auth_cookie
string | null
Für die authentifizierte Prüfung des eingeloggten Bereichs. Verschlüsselt gespeichert, nie in Logs oder Berichten.
auth_header
string | null
Wie `auth_cookie`, als Header-Zeile.

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. Alles Weitere — Fortschritt, Befunde, Artefakte — hängt daran.

Fehlercodes

202
Eingereiht.
400
Eingabe ungültig (`validation_failed`).
402
Kontingent erschöpft (`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`).
429
Zu viele Anfragen (`rate_limited`).

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.

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