{"service":"Virenscan","version":"1.10.0","endpoints":{"health":"GET /health","health_detailed":"GET /health/detailed (X-API-Key)","scan":"POST /scan (multipart field 'file', header X-API-Key)","error_codes":"Siehe error_codes in dieser Antwort","mcp":"POST /mcp (JSON-RPC 2.0, API-Key: Bearer oder X-API-Key)","admin":"GET /admin (Login: Benutzer/Passwort oder API-Key)"},"scan_usage":{"method":"POST","path":"/scan","headers":{"X-API-Key":"Pflicht","X-Content-SHA256":"Optional – SHA-256 der rohen Datei-Bytes (64 Hex), sonst weglassen","Content-Type":"multipart/form-data"},"body":"Ein Feld exakt namens 'file' mit der Binärdatei","curl_example":"curl -H \"X-API-Key: $API_KEY\" -F \"file=@datei.pdf\" https://HOST/scan"},"http_semantics":{"200":"Datei sauber (clean: true) – kein Retry nötig","409":"Malware erkannt (clean: false) – ERWARTETES Ergebnis, nicht retryen, nicht als Serverfehler werten","413":"Datei/Request zu groß. ACHTUNG: Kann vom Reverse-Proxy (Traefik) als Klartext OHNE JSON-Body kommen – immer zuerst den Statuscode prüfen, erst dann JSON parsen","429":"Rate-Limit – Retry-After abwarten (rate_limit_type: ip oder api_key)","503":"ClamAV nicht bereit – Retry-After, zuerst GET /health bis scan_accepting=true","504":"Scan-Timeout – gleiche Datei später erneut senden (Cache kann Ergebnis liefern)"},"integration_hint":"Malware = HTTP 409 (kein Serverfehler, retryable: false). Erfolg = 200 mit clean:true. Header X-Scan-Result: clean|infected bei Scan-Antworten. Alle Fehlerantworten enthalten error_code, retryable, user_action, request_id.","error_codes":[{"error_code":"ADMIN_SESSION_REQUIRED","retryable":false,"user_action":"In der Admin-Oberfläche anmelden."},{"error_code":"APIKEY_NOT_FOUND","retryable":false,"user_action":"API-Key existiert nicht (evtl. bereits gelöscht)."},{"error_code":"APIKEY_VALIDATION_ERROR","retryable":false,"user_action":"Eingaben prüfen (Bezeichnung, Scopes)."},{"error_code":"API_KEY_INVALID","retryable":false,"user_action":"API-Key prüfen oder Administrator kontaktieren."},{"error_code":"API_KEY_MISSING","retryable":false,"user_action":"Header X-API-Key setzen."},{"error_code":"API_KEY_WRONG_HEADER","retryable":false,"user_action":"API-Key in X-API-Key senden, nicht Authorization: Bearer."},{"error_code":"AUTHORIZATION_UNSUPPORTED","retryable":false,"user_action":"Authorization-Header entfernen; nur X-API-Key verwenden."},{"error_code":"CLAMAV_UNAVAILABLE","retryable":true,"user_action":"Retry-After abwarten; zuerst GET /health prüfen."},{"error_code":"CLAMD_CIRCUIT_OPEN","retryable":true,"user_action":"Retry-After abwarten; ClamAV ist kurz überlastet."},{"error_code":"CLAMD_MALFORMED_RESPONSE","retryable":true,"user_action":"Erneut versuchen; bei Wiederholung Support mit request_id."},{"error_code":"CONTENT_SHA256_MISMATCH","retryable":false,"user_action":"Hash der rohen Datei-Bytes prüfen oder Header weglassen."},{"error_code":"CSRF_TOKEN_INVALID","retryable":false,"user_action":"Seite neu laden und erneut versuchen."},{"error_code":"DOWNLOAD_FAILED","retryable":true,"user_action":"Download-URL prüfen und erneut versuchen."},{"error_code":"EMPTY_FILE","retryable":false,"user_action":"Nicht-leere Datei hochladen."},{"error_code":"FILE_NOT_FOUND","retryable":false,"user_action":"Dateipfad/URL prüfen – Datei nicht gefunden."},{"error_code":"FILE_TOO_LARGE","retryable":false,"user_action":"Kleinere Datei wählen oder MAX_UPLOAD_BYTES prüfen."},{"error_code":"FORBIDDEN","retryable":false,"user_action":"Zugriff nur von vertrauenswürdigen Quellen."},{"error_code":"INTERNAL_ERROR","retryable":true,"user_action":"Erneut versuchen; Support mit request_id kontaktieren."},{"error_code":"INVALID_CONTENT_LENGTH","retryable":false,"user_action":"Content-Length weglassen oder korrekt setzen (gesamter Request)."},{"error_code":"INVALID_CONTENT_SHA256","retryable":false,"user_action":"X-Content-SHA256 weglassen oder als 64 Hex-Zeichen setzen."},{"error_code":"INVALID_CONTENT_TYPE","retryable":false,"user_action":"Content-Type multipart/form-data verwenden."},{"error_code":"INVALID_EMAIL","retryable":false,"user_action":"Nur in .env konfigurierte Empfänger verwenden."},{"error_code":"INVALID_FILE_FIELD","retryable":false,"user_action":"Feld 'file' muss die Binärdatei sein."},{"error_code":"INVALID_FILE_REFERENCE","retryable":false,"user_action":"Datei-Referenz prüfen (HTTPS-URL, Connector-Objekt oder erlaubter Pfad)."},{"error_code":"INVALID_INPUT","retryable":false,"user_action":"Eingabe prüfen: genau eine Dateiquelle angeben."},{"error_code":"LAST_ADMIN_PROTECTED","retryable":false,"user_action":"Zuerst einen weiteren aktiven Administrator anlegen."},{"error_code":"LOCAL_FILE_DISABLED","retryable":false,"user_action":"Lokale Dateien sind deaktiviert (MCP_ALLOW_LOCAL_FILES)."},{"error_code":"LOGIN_DISABLED","retryable":false,"user_action":"Konto ist deaktiviert – Administrator kontaktieren."},{"error_code":"LOGIN_INVALID","retryable":false,"user_action":"Benutzername und Passwort prüfen."},{"error_code":"MCP_DISABLED","retryable":false,"user_action":"MCP-Server aktivieren (MCP_ENABLED=true)."},{"error_code":"MCP_INVALID_REQUEST","retryable":false,"user_action":"JSON-RPC-Feld 'method' prüfen."},{"error_code":"MCP_PARSE_ERROR","retryable":false,"user_action":"Gültiges JSON-RPC 2.0 senden."},{"error_code":"METHOD_NOT_ALLOWED","retryable":false,"user_action":"HTTP-Methode prüfen (Allow-Header beachten)."},{"error_code":"MISSING_FILE_FIELD","retryable":false,"user_action":"multipart/form-data mit Feldname 'file' senden."},{"error_code":"MULTIPART_INVALID","retryable":false,"user_action":"Multipart-Body prüfen (Boundary im Content-Type, korrektes Format)."},{"error_code":"MULTIPART_TOO_MANY_FIELDS","retryable":false,"user_action":"Nur das Feld 'file' mitsenden."},{"error_code":"MULTIPLE_FILE_FIELDS","retryable":false,"user_action":"Nur eine Datei pro Request (ein 'file'-Feld)."},{"error_code":"MULTIPLE_SOURCES","retryable":false,"user_action":"Nur eine Dateiquelle senden (content_base64 ODER file_url ODER …)."},{"error_code":"NOT_FOUND","retryable":false,"user_action":"URL prüfen; verfügbare Endpunkte: GET /."},{"error_code":"PERMISSION_DENIED","retryable":false,"user_action":"Fehlende Berechtigung – Administrator kontaktieren."},{"error_code":"RATE_LIMIT_EXCEEDED","retryable":true,"user_action":"Retry-After abwarten."},{"error_code":"REPORT_TOKEN_INVALID","retryable":false,"user_action":"STATUS_REPORT_CRON_TOKEN prüfen."},{"error_code":"SCAN_FAILED","retryable":true,"user_action":"Erneut versuchen; bei Wiederholung Support mit request_id."},{"error_code":"SCAN_TIMEOUT","retryable":true,"user_action":"Gleiche Datei in 1–2 Minuten erneut senden (Cache kann Ergebnis liefern)."},{"error_code":"SCOPE_MISSING","retryable":false,"user_action":"API-Key mit passendem Scope verwenden (z. B. scan:run)."},{"error_code":"SETTINGS_NOT_WRITABLE","retryable":false,"user_action":"Konfigurationsdatei auf dem Server prüfen (ENV_FILE_PATH / Volume-Mount)."},{"error_code":"SETTINGS_NO_CHANGES","retryable":false,"user_action":"Mindestens einen Wert ändern."},{"error_code":"SETTINGS_VALIDATION_ERROR","retryable":false,"user_action":"Eingaben prüfen und erneut speichern."},{"error_code":"TOO_MANY_REQUESTS","retryable":true,"user_action":"Retry-After abwarten; weniger parallele Uploads."},{"error_code":"UPLOAD_READ_FAILED","retryable":true,"user_action":"Upload erneut versuchen."},{"error_code":"UPLOAD_STALL","retryable":true,"user_action":"Netzwerk prüfen und Upload erneut versuchen."},{"error_code":"UPLOAD_TIMEOUT","retryable":true,"user_action":"Upload erneut versuchen."},{"error_code":"USERNAME_TAKEN","retryable":false,"user_action":"Anderen Benutzernamen wählen."},{"error_code":"USER_MANAGEMENT_UNAVAILABLE","retryable":false,"user_action":"Benutzerverwaltung ist in dieser Sitzung nicht verfügbar (Break-Glass-Login)."},{"error_code":"USER_NOT_FOUND","retryable":false,"user_action":"Benutzer existiert nicht (evtl. bereits gelöscht)."},{"error_code":"USER_VALIDATION_ERROR","retryable":false,"user_action":"Eingaben prüfen (Benutzername, Passwort, Rollen)."},{"error_code":"VALIDATION_ERROR","retryable":false,"user_action":"Anfrageformat prüfen (siehe GET /)."},{"error_code":"WRONG_FILE_FIELD","retryable":false,"user_action":"Feld exakt 'file' nennen (nicht document/upload)."}],"openapi":"/docs (nur wenn DOCS_ENABLED=true)","documentation":"docs/AGENT-HANDBUCH.md","mcp":{"endpoint":"POST /mcp","protocol":"Model Context Protocol (JSON-RPC 2.0 über HTTP)","auth":"Authorization: Bearer <API-Key> oder X-API-Key","tools":["scan_file","scan_text","get_health","get_metrics","get_capabilities","list_error_codes"],"handbook":"docs/MCP-HANDBUCH.md","note":"verdict=infected ist ein gültiges Ergebnis, kein Fehler. Zuerst get_capabilities."},"admin_api":{"login":"POST /admin/login (form: username+password oder api_key)","logout":"POST /admin/logout","status":"GET /admin/api/status (session cookie)","settings":"GET /admin/api/settings","settings_update":"PATCH /admin/api/settings (JSON: { updates: { ENV_KEY: value } })","logs":"GET /admin/api/logs?page=1&page_size=50&q=…","scan":"POST /admin/api/scan","test_email":"POST /admin/api/test-email","send_report":"POST /admin/api/send-report","diagnostics":"GET /admin/api/diagnostics","users":"GET/POST/PATCH/DELETE /admin/api/users (users:manage)","integration":"GET /admin/api/integration (apikeys:manage)","integration_guide":"GET /admin/api/integration/guide.md (apikeys:manage)","keys":"GET/POST/PATCH/DELETE /admin/api/keys (apikeys:manage)"},"request_id":"3f28052f-ce0e-4878-bc04-19afa82f2a16"}