SnapOtter/apps/docs/de/api/rest.md

---
description: "Vollständige REST-API-Referenz. Tool-Endpunkte, Stapelverarbeitung, Pipelines, Dateibibliothek, Authentifizierung, Teams und Admin-Operationen."
i18n_output_hash: 8efd33eca67a
i18n_source_hash: 7e0a0db4abe0
i18n_provenance: human
---

# REST-API-Referenz {#rest-api-reference}

Interaktive API-Dokumentation mit Beispielen für Anfragen und Antworten ist verfügbar unter [http://localhost:1349/api/docs](http://localhost:1349/api/docs).

Maschinenlesbare Spezifikationen:
- `/api/v1/openapi.yaml` - OpenAPI-3.1-Spezifikation
- `/llms.txt` - LLM-freundliche Zusammenfassung
- `/llms-full.txt` - Vollständige LLM-freundliche Dokumentation

## Authentifizierung {#authentication}

Alle Endpunkte erfordern eine Authentifizierung, sofern nicht `AUTH_ENABLED=false`.

### Sitzungs-Token {#session-token}

```bash
# Login
curl -X POST http://localhost:1349/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin"}'
# Returns: {"token":"<session-token>"}

# Use token (tool routes are POST multipart)
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer <session-token>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

Sitzungen laufen nach 7 Tagen ab (konfigurierbar über `SESSION_DURATION_HOURS`).

### API-Schlüssel {#api-keys}

```bash
# Create a key (returns key once - store it)
curl -X POST http://localhost:1349/api/v1/api-keys \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"name":"my-script"}'
# Returns: {"key":"si_<96 hex chars>","id":"...","name":"my-script"}

# Use the key
curl -X POST http://localhost:1349/api/v1/tools/image/resize \
  -H "Authorization: Bearer si_<your-key>" \
  -F "file=@photo.jpg" \
  -F 'settings={"width":800}'
```

Schlüssel erhalten das Präfix `si_` und werden als scrypt-Hashes gespeichert. Der Rohschlüssel wird einmal angezeigt und ist danach nie wieder abrufbar.

### Auth-Endpunkte {#auth-endpoints}

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `POST` | `/api/auth/login` | Öffentlich | Anmelden, Sitzungs-Token erhalten |
| `POST` | `/api/auth/logout` | Auth | Aktuelle Sitzung beenden |
| `GET` | `/api/auth/session` | Auth | Aktuelle Sitzung validieren |
| `POST` | `/api/auth/change-password` | Auth | Eigenes Passwort ändern (macht alle anderen Sitzungen + API-Schlüssel ungültig) |
| `GET` | `/api/auth/users` | Admin | Alle Benutzer auflisten |
| `POST` | `/api/auth/register` | Admin | Neuen Benutzer erstellen |
| `PUT` | `/api/auth/users/:id` | Admin | Benutzerrolle oder -team aktualisieren |
| `POST` | `/api/auth/users/:id/reset-password` | Admin | Passwort eines Benutzers zurücksetzen |
| `DELETE` | `/api/auth/users/:id` | Admin | Einen Benutzer löschen |
| `GET` | `/api/v1/config/auth` | Öffentlich | Prüfen, ob die Authentifizierung aktiviert ist (`{ authEnabled: bool }`) |
| `POST` | `/api/auth/mfa/enroll` | Auth | TOTP-MFA-Registrierung starten. Erfordert das Enterprise-Feature `mfa` |
| `POST` | `/api/auth/mfa/verify` | Auth | MFA-Registrierung mit einem TOTP-Code bestätigen |
| `POST` | `/api/auth/mfa/complete` | Öffentlich | Eine ausstehende MFA-Login-Challenge abschließen |
| `POST` | `/api/auth/mfa/disable` | Auth | MFA für den aktuellen Benutzer deaktivieren |
| `POST` | `/api/auth/users/:id/mfa/reset` | Admin (`users:manage`) | MFA für einen Benutzer zurücksetzen |
| `GET` | `/api/auth/oidc/login` | Öffentlich | OIDC-Login starten, wenn OIDC aktiviert ist |
| `GET` | `/api/auth/oidc/callback` | Öffentlich | OIDC-Autorisierungs-Callback |
| `GET` | `/api/auth/saml/metadata` | Öffentlich | SAML-SP-Metadaten-XML, wenn SAML aktiviert ist |
| `GET` | `/api/auth/saml/login` | Öffentlich | SAML-Login starten |
| `POST` | `/api/auth/saml/callback` | Öffentlich | SAML Assertion Consumer Service |

Wenn MFA für einen Benutzer aktiviert ist, gibt `POST /api/auth/login` statt eines Sitzungs-Tokens `{"requiresMfa":true,"mfaToken":"...","mfaRequired":true|false}` zurück. Senden Sie dieses `mfaToken` zusammen mit einem TOTP- oder Wiederherstellungscode an `/api/auth/mfa/complete`.

### Berechtigungen {#permissions}

| Berechtigung | Admin | Benutzer |
|-----------|:-----:|:----:|
| Tools verwenden | ✓ | ✓ |
| Eigene Dateien/Pipelines/API-Schlüssel | ✓ | ✓ |
| Dateien/Pipelines/Schlüssel aller Benutzer sehen | ✓ | - |
| Einstellungen schreiben | ✓ | - |
| Benutzer & Teams verwalten | ✓ | - |
| Branding verwalten | ✓ | - |

## Health-Check {#health-check}

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/health` | Öffentlich | Grundlegender Health-Check. Gibt `{"status":"healthy","version":"..."}` mit 200 zurück oder `{"status":"unhealthy"}` mit 503, wenn die Datenbank nicht erreichbar ist. |
| `GET` | `/api/v1/readyz` | Öffentlich | Readiness-Probe. Prüft PostgreSQL, Redis, Speicherplatz und S3, sofern konfiguriert. Gibt 503 zurück, wenn die Instanz keinen Datenverkehr erhalten sollte. |
| `GET` | `/api/v1/admin/health` | Admin (`system:health`) | Detaillierte Diagnose einschließlich Betriebszeit, Speichermodus, Datenbankstatus, Warteschlangenstatus und GPU-Verfügbarkeit. |

## Tools verwenden {#using-tools}

Jedes Tool folgt demselben Muster:

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId> \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'settings={"width":800,"height":600}'

# Batch (returns ZIP)
curl -X POST http://localhost:1349/api/v1/tools/<section>/<toolId>/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'settings={...}'
```

`<section>` ist einer der Werte `image`, `video`, `audio`, `pdf` oder `files`.

- Der Upload ist `multipart/form-data`.
- `settings` ist ein JSON-String mit tool-spezifischen Optionen.
- `clientJobId` ist ein optionales Formularfeld für vom Aufrufer bereitgestellte Fortschrittskorrelation.
- `fileId` ist ein optionales Formularfeld, das auf ein vorhandenes Element der Dateibibliothek verweist. Wenn vorhanden, wird die verarbeitete Ausgabe als neue Version gespeichert und die Antwort enthält `savedFileId`.
- **Schnelle Tools** geben in der Regel 200-JSON zurück: `{"jobId":"...","downloadUrl":"/api/v1/download/<jobId>/<filename>","originalSize":1234,"processedSize":567}`. Rufen Sie die verarbeitete Datei von `downloadUrl` ab.
- **Jedes eingereihte Tool** kann 202-JSON zurückgeben, wenn es lange läuft oder das synchrone Warte-Zeitfenster überschreitet: `{"jobId":"...","async":true}`. Verbinden Sie sich mit SSE für den Fortschritt und laden Sie die Datei nach Abschluss herunter (siehe [Fortschrittsverfolgung](#progress-tracking)).
- **Batch**-Routen geben ein direkt gestreamtes ZIP-Archiv zurück (mit `X-Job-Id`-Header) für Tools, die im generischen Batch-Register registriert sind.

## Tools-Referenz {#tools-reference}

### Konvertierungs-Presets {#conversion-presets}

Der gemeinsame Katalog enthält 83 dedizierte Konvertierungs-Preset-Endpunkte wie `jpg-to-png`, `mov-to-mp4`, `m4a-to-mp3`, `pdf-to-jpg` und `excel-to-csv`. Presets sind vollwertige Tool-Routen:

`POST /api/v1/tools/<section>/<presetId>`

Jedes Preset legt das Ausgabeformat fest und delegiert an ein Basis-Tool wie `convert`, `convert-video`, `extract-audio`, `convert-audio`, `image-to-pdf`, `pdf-to-image`, `svg-to-raster` oder `convert-spreadsheet`. Die vollständige Routentabelle und die optionalen Einstellungen finden Sie unter [Konvertierungs-Presets](/de/tools/conversion-presets).

### Grundlagen {#essentials}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `resize` | Größe ändern | `width`, `height`, `fit` (cover/contain/fill/inside/outside), `percentage`, `withoutEnlargement`, plus 23 Social-Media-Presets |
| `crop` | Zuschneiden | `left`, `top`, `width`, `height`, `unit` (px/Prozent) |
| `rotate` | Drehen & Spiegeln | `angle`, `horizontal` (bool), `vertical` (bool) |
| `convert` | Konvertieren | `format` (jpg/png/webp/avif/tiff/gif/heic/heif), `quality` |
| `compress` | Komprimieren | `mode` (quality/targetSize), `quality` (1–100), `targetSizeKb` |

### Optimierung {#optimization}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `optimize-for-web` | Für Web optimieren | `format` (webp/jpeg/avif/png), `quality`, `maxWidth`, `maxHeight`, `progressive`, `stripMetadata` |
| `strip-metadata` | Metadaten entfernen | - |
| `edit-metadata` | Metadaten bearbeiten | `title`, `description`, `author`, `copyright`, `keywords`, `gps` (lat/lon), `dateTime` |
| `bulk-rename` | Massen-Umbenennung | `pattern` (unterstützt `{n}`, `{date}`, `{original}`), `startIndex`, `padding` |
| `image-to-pdf` | Bild zu PDF | `pageSize` (A4/Letter/...), `orientation`, `margin`, `targetSize` ({value, unit}) |
| `favicon` | Favicon-Generator | `padding`, `backgroundColor`, `borderRadius` - generiert alle Standardgrößen |

### Anpassungen {#adjustments}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `adjust-colors` | Farben anpassen | `brightness`, `contrast`, `exposure`, `saturation`, `temperature`, `tint`, `hue`, `sharpness`, `red`, `green`, `blue`, `effect` (none/grayscale/sepia/invert) |
| `sharpening` | Schärfen | `method` (adaptive/unsharp-mask/high-pass), `sigma`, `m1`, `m2`, `x1`, `y2`, `y3`, `amount`, `radius`, `threshold`, `strength`, `kernelSize` (3/5), `denoise` (off/light/medium/strong) |
| `replace-color` | Farbe ersetzen | `sourceColor`, `targetColor` (Ersatz), `makeTransparent`, `tolerance` |
| `color-blindness` | Farbenblindheits-Simulation | `simulationType` (protanopia/deuteranopia/tritanopia/protanomaly/deuteranomaly/tritanomaly/achromatopsia/blueConeMonochromacy, Standard \"deuteranomaly\") |
| `duotone` | Duotone | `shadow` (hex), `highlight` (hex), `intensity` (0-100) |
| `pixelate` | Verpixeln | `blockSize` (2-128), `region` ({left, top, width, height} für teilweise Verpixelung) |
| `vignette` | Vignette | `strength` (0.1-1), `color` (hex), `radius`, `softness`, `roundness`, `centerX`, `centerY` |

### KI-Tools {#ai-tools}

Alle KI-Tools laufen auf Ihrer Hardware: standardmäßig auf der CPU oder auf NVIDIA CUDA, wenn eine unterstützte NVIDIA-GPU verfügbar ist. Intel/AMD-iGPU-Beschleunigung über VA-API, Quick Sync oder OpenCL wird für KI-Inferenz derzeit nicht unterstützt. Keine Internetverbindung erforderlich.

| Tool-ID | Name | KI-Modell | Wichtige Einstellungen |
|---------|------|---------|-------------|
| `remove-background` | Hintergrund entfernen | rembg (BiRefNet / U2-Net) | `model`, `backgroundType` (transparent/color/gradient/blur/image), `backgroundColor`, `gradientColor1`, `gradientColor2`, `gradientAngle`, `blurEnabled`, `blurIntensity`, `shadowEnabled`, `shadowOpacity` |
| `upscale` | Bild-Hochskalierung | RealESRGAN | `scale` (2/4), `model`, `faceEnhance`, `denoise`, `format`, `quality` |
| `erase-object` | Objekt-Radierer | LaMa (ONNX) | Maske als zweiter Datei-Teil gesendet (Feldname `mask`), `format`, `quality` |
| `ocr` | OCR / Textextraktion | Tesseract (schnell); RapidOCR + PP-OCR ONNX (ausgewogen/am besten) | `quality` (schnell/ausgewogen/am besten), `language`, `enhance` |
| `blur-faces` | Gesichts-/PII-Unschärfe | MediaPipe | `blurRadius`, `sensitivity` |
| `smart-crop` | Smart Crop | MediaPipe + Sharp | `mode` (subject/face/trim), `strategy` (attention/entropy), `width`, `height`, `padding`, `facePreset` (closeup/head-shoulders/upper-body/half-body), `sensitivity`, `threshold`, `padToSquare`, `padColor`, `targetSize`, `quality` |
| `image-enhancement` | Bildverbesserung | Analysebasiert | `mode` (auto/exposure/contrast/color/sharpness), `strength` |
| `enhance-faces` | Gesichtsverbesserung | GFPGAN / CodeFormer | `model` (gfpgan/codeformer), `strength`, `sensitivity`, `centerFace` |
| `colorize` | KI-Kolorierung | DDColor | `intensity`, `model` |
| `noise-removal` | Rauschentfernung | Gestufte Entrauschung | `tier` (quick/balanced/quality/maximum), `strength`, `detailPreservation`, `colorNoise`, `format`, `quality` |
| `red-eye-removal` | Rote-Augen-Entfernung | Gesichts-Landmarken + Farbanalyse | `sensitivity`, `strength` |
| `restore-photo` | Fotorestaurierung | Mehrstufige Pipeline | `mode` (auto/light/heavy), `scratchRemoval`, `faceEnhancement`, `fidelity`, `denoise`, `denoiseStrength`, `colorize` |
| `passport-photo` | Passfoto | MediaPipe-Landmarken | Zweiphasiger Ablauf. Die Analyse verwendet multipart `file`; die Generierung verwendet JSON mit `countryCode`, `bgColor`, `printLayout` (none/4x6/a4), Landmarken, Bildabmessungen |
| `content-aware-resize` | Inhaltsbasierte Größenänderung | Seam Carving (caire) | `width`, `height`, `protectFaces`, `blurRadius`, `sobelThreshold`, `square` |
| `transparency-fixer` | PNG-Transparenz-Korrektur | BiRefNet HR-Matting | `defringe` (0-100), `outputFormat` (png/webp) |
| `background-replace` | Hintergrund ersetzen | rembg (BiRefNet) | `backgroundType` (color/gradient), `color` (hex), `gradientColor1`, `gradientColor2`, `gradientAngle`, `feather` (0-20), `format` (png/webp) |
| `blur-background` | Hintergrund weichzeichnen | rembg (BiRefNet) | `intensity` (1-100), `feather` (0-20), `format` (png/webp) |
| `ai-canvas-expand` | KI-Leinwand-Erweiterung | LaMa (Outpainting) | `extendTop`, `extendRight`, `extendBottom`, `extendLeft` (px), `tier` (fast/balanced/high), `format`, `quality` |

### Wasserzeichen & Overlay {#watermark-overlay}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `watermark-text` | Text-Wasserzeichen | `text`, `font`, `fontSize`, `color`, `opacity`, `position`, `rotation`, `tile` |
| `watermark-image` | Bild-Wasserzeichen | `opacity`, `position`, `scale` - die zweite Datei ist das Wasserzeichen |
| `text-overlay` | Text-Overlay | `text`, `font`, `fontSize`, `color`, `x`, `y`, `background`, `padding`, `borderRadius` |
| `compose` | Bildkomposition | `x`, `y`, `opacity`, `blend` - die zweite Datei wird darübergelegt |
| `meme-generator` | Meme-Generator | `templateId`, `textLayout` (top-bottom/top-only/bottom-only/center/side-by-side), `textBoxes` ([{id, text}]), `fontFamily` (anton/arial-black/comic-sans/montserrat/bebas-neue/permanent-marker/roboto), `fontSize`, `textColor`, `strokeColor`, `textAlign`, `allCaps`. Unterstützt den Vorlagenmodus (JSON-Body mit `templateId`) oder den benutzerdefinierten Bildmodus (multipart mit Datei). |

### Dienstprogramme {#utilities}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `info` | Bildinformationen | - (gibt Breite, Höhe, Format, Größe, Kanäle, hasAlpha, DPI, EXIF zurück) |
| `compare` | Bildvergleich | `mode` (side-by-side/overlay/diff), `diffThreshold` - die zweite Datei ist das Vergleichsziel |
| `find-duplicates` | Duplikate finden | `threshold` (Abstand des perzeptuellen Hashs, Standard 8) - Mehrfachdatei |
| `color-palette` | Farbpalette | `count` (Anzahl der dominanten Farben), `format` (hex/rgb) |
| `qr-generate` | QR-Code-Generator | `data`, `size`, `margin`, `colorDark`, `colorLight`, `errorCorrectionLevel`, `dotStyle`, `cornerStyle`, `logo` (optionale Datei) |
| `barcode-read` | Barcode-Leser | - (erkennt automatisch QR, EAN, Code128, DataMatrix usw.) |
| `image-to-base64` | Bild zu Base64 | `format` (data-uri/plain), `mimeType` |
| `html-to-image` | HTML zu Bild | `url`, `format` (png/jpg/webp), `quality`, `fullPage`, `devicePreset` (desktop/tablet/mobile/custom), `viewportWidth`, `viewportHeight` |
| `histogram` | Histogramm | `scale` (linear/log) - gibt RGB-Histogramm-Diagramm + Statistiken pro Kanal zurück |
| `lqip-placeholder` | LQIP-Platzhalter | `width` (4-64), `blur`, `strategy` (blur/pixelate/solid), `format` (webp/png/jpeg), `quality` |
| `barcode-generate` | Barcode-Generator | `text`, `type` (code128/ean13/upca/code39/itf14/datamatrix), `scale` (1-8), `includeText` (bool). JSON-Body, kein Datei-Upload. |

### Layout & Komposition {#layout-composition}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `collage` | Collage / Raster | `template` (25+ Layouts), `gap`, `backgroundColor`, `borderRadius` - Mehrfachdatei |
| `stitch` | Zusammenfügen / Kombinieren | `direction` (horizontal/vertical/grid), `gap`, `backgroundColor`, `alignment` - Mehrfachdatei |
| `split` | Bildaufteilung | `mode` (grid/rows/cols), `rows`, `cols`, `tileWidth`, `tileHeight` |
| `border` | Rand & Rahmen | `width`, `color`, `style` (solid/gradient/pattern), `borderRadius`, `padding`, `shadow` |
| `beautify` | Screenshot verschönern | `backgroundType` (solid/linear-gradient/radial-gradient/image/transparent), `gradientStops`, `padding`, `borderRadius`, `shadowPreset`, `frame` (none/macos-light/macos-dark/windows-light/windows-dark/browser-light/browser-dark/iphone/macbook/ipad/...), `socialPreset` (none/twitter/linkedin/instagram-square/instagram-story/facebook/producthunt), `watermarkText`, `outputFormat` |
| `circle-crop` | Kreis-Zuschnitt | `zoom` (1-5), `offsetX`, `offsetY`, `borderWidth`, `borderColor`, `background` (transparent/hex), `outputSize` |
| `image-pad` | Bild auffüllen | `target` (16:9/9:16/1:1/4:3/3:4/custom), `ratioW`, `ratioH`, `background` (color/transparent/blur), `color` (hex), `padding` (0-50%) |
| `sprite-sheet` | Sprite-Sheet | `columns` (1-16), `padding`, `background` (hex), `format` (png/webp/jpeg), `quality` - Mehrfachdatei (2-64 Bilder) |

### Format & Konvertierung {#format-conversion}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `svg-to-raster` | SVG zu Raster | `format` (png/jpeg/webp/avif/tiff/gif/heif), `width`, `height`, `scale`, `dpi`, `background` |
| `vectorize` | Bild zu SVG | `colorMode` (bw/color), `threshold`, `colorPrecision`, `filterSpeckle`, `pathMode` (none/polygon/spline) |
| `gif-tools` | GIF-Tools | `action` (resize/optimize/reverse/speed/extract-frames/rotate/add-text), aktionsspezifische Parameter |
| `gif-webp` | GIF/WebP-Konverter | `quality` (1-100), `lossless` (bool), `resizePercent` (10-100) |

### Video-Tools {#video-tools}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `convert-video` | Video konvertieren | `format` (mp4/mov/webm/avi/mkv), `quality` (high/balanced/small) |
| `compress-video` | Video komprimieren | `quality` (light/balanced/strong), `resolution` (original/1080p/720p/480p) |
| `trim-video` | Video zuschneiden | `startS`, `endS`, `precise` (bool, bildgenauer Schnitt) |
| `mute-video` | Video stummschalten | - |
| `video-to-gif` | Video zu GIF | `fps` (1-30), `width`, `startS`, `durationS` (max. 60s) |
| `resize-video` | Video-Größe ändern | `width`, `height`, `preset` (custom/2160p/1440p/1080p/720p/480p/360p) |
| `crop-video` | Video zuschneiden (Crop) | `width`, `height`, `x`, `y` |
| `rotate-video` | Video drehen | `transform` (cw90/ccw90/180/hflip/vflip) |
| `change-fps` | FPS ändern | `fps` (1-120) |
| `video-color` | Video-Farbe | `brightness`, `contrast`, `saturation`, `gamma` |
| `video-speed` | Video-Geschwindigkeit | `factor` (0.25-4), `keepPitch` (bool) |
| `reverse-video` | Video umkehren | - (max. 5 Minuten) |
| `video-loudnorm` | Audio normalisieren | - (EBU R128) |
| `aspect-pad` | Seitenverhältnis auffüllen | `target` (16:9/9:16/1:1/4:3/3:4), `color` (hex) |
| `blur-pad` | Unschärfe-Auffüllung | `target` (16:9/9:16/1:1/4:3/3:4), `blur` (2-50) |
| `watermark-video` | Video mit Wasserzeichen | `text`, `position`, `fontSize`, `opacity`, `color` |
| `stabilize-video` | Video stabilisieren | `smoothing` (5-60, in Frames) |
| `gif-to-video` | GIF zu Video | `format` (mp4/webm/mov) |
| `video-to-webp` | Video zu WebP | `fps`, `width`, `quality`, `loop` (bool) |
| `video-to-frames` | Video zu Frames | `mode` (all/nth/timestamps), `n`, `timestamps`, `format` (png/jpg) |
| `merge-videos` | Videos zusammenführen | - (Mehrfachdatei, auf die Auflösung des ersten Videos normalisiert) |
| `replace-audio` | Audio ersetzen | - (Video- + Audiodatei, zwei Dateien) |
| `burn-subtitles` | Untertitel einbrennen | `fontSize` (8-72) - Video- + Untertiteldatei |
| `embed-subtitles` | Untertitel einbetten | `language` (ISO-639-2/B-Code) - Video- + Untertiteldatei |
| `extract-subtitles` | Untertitel extrahieren | - (gibt SRT aus) |
| `images-to-video` | Bilder zu Video | `secondsPerImage` (0.5-10), `resolution` (1080p/720p/square), `fps` - Mehrfachdatei |
| `video-metadata` | Video-Metadaten bereinigen | - |
| `auto-subtitles` | Auto-Untertitel (KI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `format` (srt/vtt) |
| `extract-audio` | Audio extrahieren | `format` (mp3/wav/m4a/ogg) |

### Audio-Tools {#audio-tools}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `convert-audio` | Audio konvertieren | `format` (mp3/wav/ogg/flac/m4a), `bitrateKbps` (32-320) |
| `trim-audio` | Audio zuschneiden | `startS`, `endS` |
| `volume-adjust` | Lautstärke anpassen | `gainDb` (-30 bis 30) |
| `normalize-audio` | Audio normalisieren | - (EBU R128, -16 LUFS) |
| `fade-audio` | Audio ein-/ausblenden | `fadeInS` (0-30), `fadeOutS` (0-30) |
| `reverse-audio` | Audio umkehren | - |
| `audio-speed` | Audio-Geschwindigkeit | `factor` (0.25-4) |
| `pitch-shift` | Tonhöhe verschieben | `semitones` (-12 bis 12) |
| `audio-channels` | Audio-Kanäle | `mode` (stereo-to-mono/mono-to-stereo/swap) |
| `silence-removal` | Stille entfernen | `thresholdDb` (-80 bis -20), `minSilenceS` (0.1-5) |
| `noise-reduction` | Rauschunterdrückung | `strength` (light/medium/strong) |
| `merge-audio` | Audio zusammenführen | `format` (mp3/wav/flac/m4a) - Mehrfachdatei |
| `split-audio` | Audio aufteilen | `mode` (time/parts/silence), `segmentS`, `parts`, `thresholdDb`, `minSilenceS` |
| `ringtone-maker` | Klingelton-Ersteller | `startS`, `durationS` (1-30) |
| `waveform-image` | Wellenform-Bild | `width`, `height`, `color` (hex) |
| `audio-metadata` | Audio-Metadaten | `strip` (bool), `title`, `artist`, `album` |
| `transcribe-audio` | Audio transkribieren (KI) | `language` (auto/en/de/fr/es/zh/ja/ko/id/th/vi), `outputFormat` (txt/srt/vtt) |

### Dokument-Tools {#document-tools}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `merge-pdf` | PDFs zusammenführen | - (Mehrfachdatei, bis zu 20 PDFs) |
| `split-pdf` | PDF aufteilen | `mode` (range/every), `range`, `everyN` (1-500) |
| `compress-pdf` | PDF komprimieren | `mode` (quality/targetSize), `quality` (1-100), `targetSizeKb` |
| `rotate-pdf` | PDF drehen | `angle` (90/180/270), `range` (Seitenbereich) |
| `extract-pages` | Seiten extrahieren | `range` (qpdf-Syntax, z.B. \"1-5,8,10-z\") |
| `remove-pages` | Seiten entfernen | `pages` (zu entfernender qpdf-Bereich) |
| `organize-pdf` | PDF organisieren | `order` (qpdf-Seitenreihenfolge, z.B. \"3,1,2,5-z\") |
| `protect-pdf` | PDF schützen | `userPassword`, `ownerPassword` (AES-256) |
| `unlock-pdf` | PDF entsperren | `password` |
| `repair-pdf` | PDF reparieren | - |
| `linearize-pdf` | PDF für Web optimieren | - (linearisieren für schnelle Web-Anzeige) |
| `grayscale-pdf` | PDF in Graustufen | - |
| `pdfa-convert` | PDF/A konvertieren | - (Archiv-PDF/A-2) |
| `crop-pdf` | PDF zuschneiden | `margin` (0-2000 Punkte) |
| `nup-pdf` | N-up PDF | `perSheet` (2/3/4/8/9/12/16) |
| `booklet-pdf` | Broschüren-PDF | `perSheet` (2/4/6/8) |
| `watermark-pdf` | PDF mit Wasserzeichen | `text`, `position`, `fontSize`, `opacity`, `rotation` |
| `pdf-page-numbers` | PDF-Seitenzahlen | `position` (bl/bc/br/tl/tc/tr), `fontSize` |
| `flatten-pdf` | PDF reduzieren (Flatten) | - (fixiert Formulare und Anmerkungen) |
| `redact-pdf` | PDF schwärzen (Redact) | `terms` (string[]), `caseSensitive` (bool) |
| `sign-pdf` | PDF signieren | Benutzerdefinierte multipart-Route mit PDF `file`, Signaturdateien `sig0`, `sig1` und `placements` JSON-Array |
| `pdf-to-text` | PDF zu Text | - |
| `pdf-to-word` | PDF zu Word | - |
| `pdf-metadata` | PDF-Metadaten | `title`, `author`, `subject`, `keywords` |
| `convert-document` | Dokument konvertieren | `format` (docx/odt/rtf/txt) |
| `convert-presentation` | Präsentation konvertieren | `format` (pptx/odp) |
| `convert-spreadsheet` | Tabellenkalkulation konvertieren | `format` (xlsx/ods/csv) |
| `excel-to-pdf` | Excel zu PDF | - |
| `word-to-pdf` | Word zu PDF | - |
| `powerpoint-to-pdf` | PowerPoint zu PDF | - |
| `html-to-pdf` | HTML zu PDF | - (Remote-Ressourcen deaktiviert) |
| `markdown-to-docx` | Markdown zu Word | - |
| `markdown-to-html` | Markdown zu HTML | - |
| `markdown-to-pdf` | Markdown zu PDF | - (Remote-Ressourcen deaktiviert) |
| `epub-convert` | EPUB konvertieren | `format` (pdf/docx/html/md) |
| `to-epub` | Zu EPUB konvertieren | - (akzeptiert .docx, .md, .html, .txt) |
| `ocr-pdf` | PDF-OCR (KI) | `quality` (fast/balanced/best), `language` (auto/en/de/fr/es/zh/ja/ko), `pages` |
| `pdf-to-image` | PDF zu Bild | `pages` (all/range), `format`, `dpi`, `quality` |
| `pdf-to-jpg` | PDF zu JPG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-png` | PDF zu PNG | `pages`, `dpi`, `quality`, `colorMode` |
| `pdf-to-tiff` | PDF zu TIFF | `pages`, `dpi`, `quality`, `colorMode` |

### Datei-Tools {#file-tools}

| Tool-ID | Name | Wichtige Einstellungen |
|---------|------|-------------|
| `chart-maker` | Diagramm-Ersteller | `kind` (bar/line/pie), `title`, `width`, `height` |
| `csv-excel` | CSV zu Excel | `sheet` (Arbeitsblattnummer für XLSX-Eingabe) - bidirektional |
| `csv-json` | CSV zu JSON | `pretty` (bool) - bidirektional |
| `json-xml` | JSON zu XML | `pretty` (bool) - bidirektional |
| `split-csv` | CSV aufteilen | `rowsPerFile` (1-1000000), `keepHeader` (bool) |
| `merge-csvs` | CSVs zusammenführen | - (Mehrfachdatei, übereinstimmende Spalten) |
| `yaml-json` | YAML / JSON | - (bidirektional) |
| `xml-to-csv` | XML zu CSV | - (findet automatisch sich wiederholende Elemente) |
| `excel-to-csv` | Excel zu CSV | dediziertes Konvertierungs-Preset, gestützt auf `convert-spreadsheet` |
| `create-zip` | ZIP erstellen | - (Mehrfachdatei, 2-50 Dateien) |
| `extract-zip` | ZIP extrahieren | - (Bomben-geschützt) |

### HTML zu Bild {#html-to-image}

Eine Webseite als Bild erfassen. Anders als andere Tools akzeptiert dieser Endpunkt `application/json` statt multipart-Formulardaten (kein Datei-Upload erforderlich).

**Endpunkt:** `POST /api/v1/tools/image/html-to-image`

**Content-Type:** `application/json`

| Parameter | Typ | Standard | Beschreibung |
|-----------|------|---------|-------------|
| `url` | string | (erforderlich) | Zu erfassende URL (nur http/https) |
| `format` | string | `"png"` | Ausgabeformat: `jpg`, `png`, `webp` |
| `quality` | number | `90` | Qualität 1-100 (nur JPG/WebP) |
| `fullPage` | boolean | `false` | Vollständige scrollbare Seite erfassen |
| `devicePreset` | string | `"desktop"` | `desktop`, `tablet`, `mobile`, `custom` |
| `viewportWidth` | number | `1280` | Benutzerdefinierte Viewport-Breite 320-3840 |
| `viewportHeight` | number | `720` | Benutzerdefinierte Viewport-Höhe 320-2160 |

**Beispiel:**

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/html-to-image \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://snapotter.com", "format": "png", "devicePreset": "desktop"}'
```

**Antwort:**

```json
{
  "jobId": "uuid",
  "downloadUrl": "/api/v1/download/{jobId}/screenshot.png",
  "originalSize": 0,
  "processedSize": 54321
}
```

### Tool-Unterrouten {#tool-sub-routes}

Einige Tools stellen zusätzliche Endpunkte über die Standard-`POST /api/v1/tools/<section>/<toolId>` hinaus bereit:

| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `GET` | `/api/v1/tools/popular` | Beliebte Tool-IDs zurückgeben, mit Rückfall auf eine kuratierte Standardliste, wenn Nutzungsdaten spärlich sind |
| `POST` | `/api/v1/tools/image/remove-background/effects` | Hintergrundeffekte (color/gradient/blur/shadow) anwenden, ohne die KI erneut auszuführen. Verwendet die zwischengespeicherte Maske aus der ursprünglichen Entfernung. |
| `POST` | `/api/v1/tools/image/edit-metadata/inspect` | Vorhandene EXIF/IPTC/XMP-Metadaten aus einem Bild lesen |
| `POST` | `/api/v1/tools/image/strip-metadata/inspect` | Metadatenfelder vor dem Entfernen prüfen |
| `POST` | `/api/v1/tools/image/passport-photo/analyze` | Phase 1: KI-Gesichtserkennung + Hintergrundentfernung. Gibt Gesichts-Landmarken und zwischengespeicherte Daten zurück. |
| `POST` | `/api/v1/tools/image/passport-photo/generate` | Phase 2: Zuschneiden, Größe ändern und Kacheln mit zwischengespeicherter Analyse. Keine erneute KI-Ausführung. |
| `POST` | `/api/v1/tools/image/gif-tools/info` | GIF-Metadaten abrufen (Frame-Anzahl, Abmessungen, Dauer) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/info` | PDF-Metadaten abrufen (Seitenanzahl, Abmessungen) |
| `POST` | `/api/v1/tools/pdf/pdf-to-image/preview` | Eine Vorschau einer bestimmten PDF-Seite erzeugen |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/info` | PDF-Metadaten für das dedizierte JPG-Preset abrufen |
| `POST` | `/api/v1/tools/pdf/pdf-to-jpg/preview` | Eine JPG-Preset-PDF-Seitenvorschau erzeugen |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/info` | PDF-Metadaten für das dedizierte PNG-Preset abrufen |
| `POST` | `/api/v1/tools/pdf/pdf-to-png/preview` | Eine PNG-Preset-PDF-Seitenvorschau erzeugen |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/info` | PDF-Metadaten für das dedizierte TIFF-Preset abrufen |
| `POST` | `/api/v1/tools/pdf/pdf-to-tiff/preview` | Eine TIFF-Preset-PDF-Seitenvorschau erzeugen |
| `POST` | `/api/v1/tools/image/svg-to-raster/batch` | Mehrere SVGs im Stapel in Raster konvertieren |
| `POST` | `/api/v1/tools/image/image-enhancement/analyze` | Bildqualität analysieren und Verbesserungsempfehlungen zurückgeben |
| `POST` | `/api/v1/tools/image/optimize-for-web/preview` | Leichtgewichtige Vorschau für die Live-Parameteranpassung. Gibt ein optimiertes Bild mit Größen-Headern zurück. |

## Stapelverarbeitung {#batch-processing}

Wenden Sie ein generisches batch-fähiges Tool auf mehrere Dateien gleichzeitig an. Gibt ein ZIP-Archiv zurück. Benutzerdefinierte Mehrfachdatei- oder mehrstufige Routen wie PDF-Signierung und PDF-zu-Bild-Preset-Routen verwenden ihren eigenen Endpunkt-Vertrag anstelle der generischen `/batch`-Route.

Das Tool `ocr-pdf` unterstützt diese generische `/batch`-Route.

```bash
curl -X POST http://localhost:1349/api/v1/tools/image/compress/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F "files=@c.jpg" \
  -F 'settings={"quality":80}'
```

Die Nebenläufigkeit wird durch `CONCURRENT_JOBS` gesteuert (Standard: automatisch anhand der CPU-Kerne erkannt). `MAX_BATCH_SIZE` begrenzt die Anzahl der Dateien pro Stapel (Standard: 100; 0 für unbegrenzt setzen).

## Pipelines {#pipelines}

### Eine Pipeline ausführen {#execute-a-pipeline}

```bash
# Single file
curl -X POST http://localhost:1349/api/v1/pipeline/execute \
  -H "Authorization: Bearer <token>" \
  -F "file=@input.jpg" \
  -F 'pipeline={"steps":[
    {"toolId":"resize","settings":{"width":1200}},
    {"toolId":"compress","settings":{"quality":80}},
    {"toolId":"watermark-text","settings":{"text":"© 2025"}}
  ]}'

# Batch (multiple files → ZIP)
curl -X POST http://localhost:1349/api/v1/pipeline/batch \
  -H "Authorization: Bearer <token>" \
  -F "files=@a.jpg" \
  -F "files=@b.jpg" \
  -F 'pipeline={"steps":[{"toolId":"resize","settings":{"width":800}}]}'
```

Die Ausgabe jedes Schritts ist die Eingabe des nächsten Schritts. Pipelines erlauben standardmäßig 20 Schritte, konfigurierbar über `MAX_PIPELINE_STEPS`. Setzen Sie `MAX_PIPELINE_STEPS=0`, um das Limit aufzuheben.

### Pipelines speichern und verwalten {#save-and-manage-pipelines}

| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `POST` | `/api/v1/pipeline/save` | Eine benannte Pipeline speichern (`name`, `description`, `steps[]`) |
| `GET` | `/api/v1/pipeline/list` | Gespeicherte Pipelines auflisten (Admins sehen alle; Benutzer sehen eigene) |
| `DELETE` | `/api/v1/pipeline/:id` | Löschen (Eigentümer oder Admin) |
| `GET` | `/api/v1/pipeline/tools` | Tool-IDs auflisten, die für Pipeline-Schritte gültig sind |

## Fortschrittsverfolgung {#progress-tracking}

Lang laufende Jobs, eingereihte Tools, Batch-Jobs und Pipelines geben Echtzeit-Fortschritt über Server-Sent Events aus. Der Fortschritts-Stream ist öffentlich und wird über die Job-ID gekennzeichnet, sodass Clients keinen Authorization-Header senden müssen, um ihn zu lesen.

```bash
# Connect to the SSE stream (jobId is in the JSON response body from the tool endpoint)
curl -N http://localhost:1349/api/v1/jobs/<jobId>/progress
```

Ereignisformat:
```
data: {"jobId":"...","type":"single","phase":"processing","stage":"Upscaling","percent":42}
data: {"jobId":"...","type":"single","phase":"complete","percent":100,"result":{"downloadUrl":"/api/v1/download/..."}}
data: {"jobId":"...","type":"batch","status":"processing","completedFiles":2,"totalFiles":5,"failedFiles":0,"errors":[]}
```

Sie können den Abbruch eines eingereihten oder laufenden Jobs mit `POST /api/v1/jobs/:jobId/cancel` anfordern. Die Antwort ist `{"canceled":true|false}`.

## Dateibibliothek {#file-library}

Dauerhafte Dateispeicherung mit Versionsverlauf.

| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `POST` | `/api/v1/upload` | Dateien in den Arbeitsbereich hochladen (temporäre Verarbeitung) |
| `POST` | `/api/v1/files/upload` | Dateien in die dauerhafte Dateibibliothek hochladen |
| `POST` | `/api/v1/files/save-result` | Ein Tool-Verarbeitungsergebnis als neue Dateiversion speichern |
| `GET` | `/api/v1/files` | Gespeicherte Dateien auflisten (paginiert, mit Suche) |
| `GET` | `/api/v1/files/:id` | Dateimetadaten + Versionskette abrufen |
| `GET` | `/api/v1/files/:id/download` | Datei herunterladen |
| `GET` | `/api/v1/files/:id/thumbnail` | 300px-JPEG-Thumbnail abrufen |
| `DELETE` | `/api/v1/files` | Dateien und ihre Versionsketten massenhaft löschen (Body: `{ ids: [...] }`) |
| `POST` | `/api/v1/fetch-urls` | Remote-URLs in den Arbeitsbereich abrufen für URL-basierte Importe |
| `POST` | `/api/v1/preview` | Eine browserkompatible WebP-Vorschau erzeugen (für HEIC/HEIF/RAW-Formate) |
| `GET` | `/api/v1/files/:id/preview` | Eine zwischengespeicherte oder erzeugte browserkompatible Vorschau für eine gespeicherte PDF-, Office-Dokument-, Video- oder Audiodatei streamen |
| `POST` | `/api/v1/preview/generate` | Eine On-Demand-MP4- oder -MP3-Vorschau für eine hochgeladene Mediendatei erzeugen, ohne sie zuerst zu speichern |
| `GET` | `/api/v1/download/:jobId/:filename` | Eine verarbeitete Datei aus einem Arbeitsbereich herunterladen |

Um ein Tool-Ergebnis automatisch in der Bibliothek zu speichern, fügen Sie `fileId` als multipart-Formularfeld hinzu, das auf eine vorhandene Bibliotheksdatei verweist. Das verarbeitete Ergebnis wird als neue Version gespeichert.

## API-Schlüssel-Verwaltung {#api-key-management}

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `POST` | `/api/v1/api-keys` | Auth | Neuen Schlüssel generieren - einmal angezeigt |
| `GET` | `/api/v1/api-keys` | Auth | Schlüssel auflisten (Name, id, lastUsedAt - nicht der Rohschlüssel) |
| `DELETE` | `/api/v1/api-keys/:id` | Auth | Schlüssel löschen |

## Teams {#teams}

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/teams` | Admin (`teams:manage`) | Teams auflisten |
| `POST` | `/api/v1/teams` | Admin (`teams:manage`) | Team erstellen |
| `PUT` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Team umbenennen |
| `DELETE` | `/api/v1/teams/:id` | Admin (`teams:manage`) | Team löschen (Standard-Team oder Teams mit Mitgliedern können nicht gelöscht werden) |

## Einstellungen {#settings}

Die Laufzeitkonfiguration verwendet eine geschlossene Menge erkannter Schlüssel. Zum Lesen ist `settings:read` und zum Schreiben `settings:write` erforderlich; Sicherheits- und Compliance-Schlüssel erfordern zusätzlich `security:manage` bzw. `compliance:manage`. Geheime Einstellungen erfordern die vollständige Administratorberechtigung, während Zugangsdaten und Zustände, die von dedizierten Endpunkten verwaltet werden, hier schreibgeschützt sind. Massenaktualisierungen werden vollständig validiert, bevor ein Wert geschrieben wird.

| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `GET` | `/api/v1/settings` | Alle Einstellungen abrufen |
| `PUT` | `/api/v1/settings` | Einstellungen massenhaft aktualisieren (JSON-Body mit Schlüssel-Wert-Paaren) |
| `GET` | `/api/v1/settings/:key` | Eine bestimmte Einstellung nach Schlüssel abrufen |

Beispielschlüssel: `disabledTools` (JSON-Array von Tool-IDs), `enableExperimentalTools` (boolescher Wert), `loginAttemptLimit` (Sicherheitsrichtlinie) und `auditRetentionDays` (Compliance-Richtlinie). Unbekannte Schlüssel werden abgelehnt.

## Einstellungen (Preferences) {#preferences}

Benutzerspezifische Einstellungen sind von den Instanzeinstellungen getrennt. Jeder authentifizierte Benutzer kann seine eigene Einstellungs-Map lesen und aktualisieren.

| Methode | Pfad | Beschreibung |
|--------|------|-------------|
| `GET` | `/api/v1/preferences` | Die Einstellungen des aktuellen Benutzers als `{ "preferences": { ... } }` abrufen |
| `PUT` | `/api/v1/preferences` | Einen oder mehrere Einstellungsschlüssel für den aktuellen Benutzer per Upsert setzen |

## Rollen {#roles}

Benutzerdefinierte Rollenverwaltung mit granularen Berechtigungen.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/roles` | Admin (`audit:read`) | Alle Rollen mit Benutzeranzahl auflisten |
| `POST` | `/api/v1/roles` | Admin (`security:manage`) | Eine benutzerdefinierte Rolle erstellen (`name`, `description`, `permissions`) |
| `PUT` | `/api/v1/roles/:id` | Admin (`security:manage`) | Eine benutzerdefinierte Rolle aktualisieren (integrierte Rollen können nicht geändert werden) |
| `DELETE` | `/api/v1/roles/:id` | Admin (`security:manage`) | Eine benutzerdefinierte Rolle löschen (integrierte Rollen können nicht gelöscht werden; betroffene Benutzer fallen auf die Rolle `user` zurück) |

Verfügbare Berechtigungen (17): `tools:use`, `files:own`, `files:all`, `apikeys:own`, `apikeys:all`, `pipelines:own`, `pipelines:all`, `settings:read`, `settings:write`, `users:manage`, `teams:manage`, `features:manage`, `system:health`, `audit:read`, `compliance:manage`, `webhooks:manage`, `security:manage`.

## Audit-Log {#audit-log}

Nur für Admins verfügbarer Endpunkt zur Überprüfung sicherheitsrelevanter Aktionen.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/audit-log` | Admin (`audit:read`) | Paginiertes Audit-Log mit optionalen Filtern |

Abfrageparameter:

| Parameter | Beschreibung |
|-----------|-------------|
| `page` | Seitennummer (Standard: 1) |
| `limit` | Einträge pro Seite (Standard: 50, max.: 100) |
| `action` | Nach Aktionstyp filtern (z.B. `ROLE_CREATED`, `ROLE_DELETED`) |
| `ip` | Nach Quell-IP-Adresse filtern |
| `from` | Einträge nach diesem ISO-8601-Datum filtern |
| `to` | Einträge vor diesem ISO-8601-Datum filtern |

## Analytics {#analytics}

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/config/analytics` | Öffentlich | Die effektive Analytics-Konfiguration abrufen (PostHog-Schlüssel, Sentry-DSN, Abtastrate). Schlüssel, DSN und Instanz-ID sind leer, wenn Analytics deaktiviert ist, entweder durch das Kompilierzeit-Baking oder die Instanzeinstellung `analyticsEnabled`. |
| `POST` | `/api/v1/feedback` | Auth | Explizites Benutzer-Feedback an das konfigurierte PostHog-Projekt als `feedback_submitted` übermitteln. Die Route beachtet das Analytics-Gate, begrenzt die Übermittlungsrate, entfernt Kontaktfelder, sofern `contactOk` nicht true ist, und akzeptiert niemals Dateiinhalte, Dateinamen, Upload-Pfade oder rohen privaten Fehlertext. Wenn Analytics deaktiviert ist, gibt sie `{ "ok": true, "accepted": false }` zurück. |
| `PUT` | `/api/v1/settings` | Admin (`settings:write`) | Den instanzweiten Opt-out setzen. Senden Sie einen JSON-Body `{ "analyticsEnabled": "false" }`, um Analytics für alle zu deaktivieren, oder `"true"`, um es wieder zu aktivieren. |

## Features / KI-Bundles {#features-ai-bundles}

KI-Feature-Bundles verwalten (KI-Modellpakete in der Docker-Umgebung installieren/deinstallieren). Bevorzugen Sie den Tool-Level-Installationsendpunkt, wenn Sie ein Tool aus benutzerdefinierter Automatisierung aktivieren: Einige KI-Tools benötigen mehr als ein gemeinsames Bundle, und dieser Endpunkt überspringt bereits installierte Bundles und reiht nur die fehlenden ein.

OCR ist eine optionale Erweiterung und keine feste Abhängigkeit. Seine `fast` Tesseract-Stufe funktioniert ohne Packung; `POST /api/v1/admin/features/ocr/install` installiert das signierte RapidOCR-Paket für `balanced` und `best` auf Linux amd64 oder arm64. Die genaue OCR-Laufzeit verwendet CPU auf reinen CPU- und NVIDIA-Hosts und erfordert mindestens 4 GiB effektiven Speicher (das konfigurierte Container-cgroup-Limit, andernfalls Hostspeicher). SnapOtter meldet `requiredMemoryBytes`, `effectiveMemoryBytes` und einen `insufficient-memory`-Kompatibilitätsgrund und lehnt eine inkompatible Installation vor dem Download ab. Dieser Speicherbedarf gilt nicht für `fast`. Das Paket muss je nach Ziel zwischen 208 und 234 MiB heruntergeladen und zwischen 409 und 488 MiB installiert werden. Der signierte Index bindet die genauen Größen, die während der Installation erzwungen werden.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/features` | Auth | Alle Feature-Bundles und ihren Installationsstatus auflisten |
| `POST` | `/api/v1/admin/features/:bundleId/install` | Admin (`features:manage`) | Ein Feature-Bundle installieren (asynchron, gibt `jobId` zur Fortschrittsverfolgung zurück) |
| `POST` | `/api/v1/admin/tools/:toolId/features/install` | Admin (`features:manage`) | Jedes von einem Tool benötigte Bundle installieren; gibt den Status queued/skipped pro Bundle zurück |
| `POST` | `/api/v1/admin/features/:bundleId/uninstall` | Admin (`features:manage`) | Ein Feature-Bundle deinstallieren und Modelldateien bereinigen |
| `GET` | `/api/v1/admin/features/disk-usage` | Admin (`features:manage`) | Den gesamten Speicherplatzverbrauch der KI-Modelle abrufen |
| `POST` | `/api/v1/admin/features/import` | Admin (`features:manage`) | Importieren Sie ein Legacy-KI-Bundle (`file`) oder eine signierte Offline-OCR-Version (`index` plus `archive`). |

Ein Air-Gap-OCR-Import muss das signierte `ocr-runtime-index.json` der Version und das passende Plattformarchiv enthalten. SnapOtter wendet dieselben Ed25519-Signatur-, Artefakt-Hash-, Kompatibilitäts-, Extraktions- und Rauchtestprüfungen an, die auch bei der Online-Installation verwendet werden:

```bash
curl -X POST http://localhost:1349/api/v1/admin/features/import \
  -H "Authorization: Bearer <admin-token>" \
  -F "index=@ocr-runtime-index.json" \
  -F "archive=@ocr-linux-amd64-cpu-py312.tar.gz"
```

Verwenden Sie das `linux-arm64-cpu-py311`-Archiv auf arm64. Ein signiertes Artefakt für ein anderes Ziel wird abgelehnt und nicht installiert.

## Admin-Operationen {#admin-operations}

Operative Endpunkte für Observability, Support, Nutzungsberichte und Backup-Status.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Das aktuelle Laufzeit-Log-Level lesen |
| `POST` | `/api/v1/admin/log-level` | Admin (`settings:write`) | Das Laufzeit-Log-Level ändern (`fatal`, `error`, `warn`, `info`, `debug`, `trace` oder `silent`) |
| `GET` | `/api/v1/metrics` | Admin (`system:health`) | Prometheus-Metriken im Textformat |
| `GET` | `/api/v1/admin/support-bundle` | Admin (`system:health`) | Ein redigiertes diagnostisches Support-Bundle-ZIP herunterladen |
| `GET` | `/api/v1/admin/usage` | Admin (`audit:read`) | Daten des Nutzungs-Dashboards, mit optionalem Abfrageparameter `days` |
| `GET` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Metadaten und Aktualitätsstatus des letzten Backups lesen |
| `POST` | `/api/v1/admin/backup-status` | Admin (`system:health`) | Ein abgeschlossenes Backup erfassen (`type`, optional `sizeBytes`, optional `notes`) |

## Enterprise-APIs {#enterprise-apis}

Diese Routen sind durch das zugehörige Enterprise-Feature lizenzgesteuert. Sie erfordern weiterhin die aufgeführte SnapOtter-Berechtigung.

**Vollständiger integrierter Admin** bedeutet, dass der authentifizierte Akteur die Rolle `admin` und den vollständigen effektiven Satz von Admin-Berechtigungen besitzt. Ein API-Schlüsselbereich, der auch nur eine Admin-Berechtigung auslässt, erfüllt die Anforderungen nicht.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/enterprise/audit/export` | Admin (`audit:read`) | Audit-Einträge als JSON oder CSV mit Filtern exportieren |
| `GET` | `/api/v1/enterprise/config/export` | Vollständiger integrierter Admin | Redigierte Instanzkonfiguration, benutzerdefinierte Rollen und Teams exportieren |
| `POST` | `/api/v1/enterprise/config/import` | Vollständiger integrierter Admin | Konfiguration importieren, mit optionalem Probelauf |
| `GET` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | Konfigurierte CIDR-Erlaubnisliste lesen |
| `PUT` | `/api/v1/enterprise/ip-allowlist` | Admin (`security:manage`) | CIDR-Erlaubnisliste mit Selbstsperrungs-Prävention aktualisieren |
| `GET` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Legal Holds für Benutzer und Teams auflisten |
| `PUT` | `/api/v1/enterprise/legal-hold` | Admin (`compliance:manage`) | Einen Legal Hold auf einen Benutzer oder ein Team anwenden oder aufheben |
| `POST` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Ein SCIM-Bearer-Token generieren, einmal zurückgegeben |
| `DELETE` | `/api/v1/enterprise/scim/token` | Admin (`users:manage`) | Das aktuelle SCIM-Bearer-Token widerrufen |
| `GET` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | SIEM-Weiterleitungskonfiguration lesen |
| `PUT` | `/api/v1/enterprise/siem/config` | Admin (`webhooks:manage`) | SIEM-Weiterleitungskonfiguration aktualisieren |
| `GET` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Webhook-Ziele auflisten |
| `POST` | `/api/v1/enterprise/webhooks` | Admin (`webhooks:manage`) | Ein Webhook-Ziel erstellen |
| `PUT` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Ein Webhook-Ziel aktualisieren |
| `DELETE` | `/api/v1/enterprise/webhooks/:index` | Admin (`webhooks:manage`) | Ein Webhook-Ziel löschen |
| `POST` | `/api/v1/enterprise/webhooks/:index/test` | Admin (`webhooks:manage`) | Eine Test-Webhook-Nutzlast senden |
| `POST` | `/api/v1/enterprise/users/:id/export` | Admin (`compliance:manage`) | Einen GDPR-Benutzerexport-Job starten |
| `GET` | `/api/v1/enterprise/users/:id/export/:jobId` | Admin (`compliance:manage`) | GDPR-Exportstatus und Download-URL lesen |
| `DELETE` | `/api/v1/enterprise/users/:id/purge` | Admin (`compliance:manage`) | Die Daten eines Benutzers nach Bestätigung dauerhaft löschen |
| `DELETE` | `/api/v1/enterprise/teams/:id/purge` | Admin (`compliance:manage`) | Die Daten eines Teams nach Bestätigung dauerhaft löschen |
| `GET` | `/api/v1/admin/version` | Admin (`system:health`) | App-, Build-, Node- und Schema-Versionsmetadaten lesen |
| `GET` | `/api/v1/admin/migrations/pending` | Admin (`system:health`) | Verpackte Migrationen mit angewendeten Migrationen vergleichen |
| `GET` | `/api/v1/admin/upgrade-check` | Admin (`system:health`) | Upgrade-Bereitschaftsprüfungen ausführen |

### SCIM 2.0 {#scim-2-0}

SCIM-Discovery-Endpunkte sind öffentlich. Benutzer- und Gruppenendpunkte erfordern das oben generierte SCIM-Bearer-Token.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/scim/v2/ServiceProviderConfig` | Öffentlich | SCIM-Server-Fähigkeiten |
| `GET` | `/api/v1/scim/v2/Schemas` | Öffentlich | SCIM-Schema-Discovery |
| `GET` | `/api/v1/scim/v2/ResourceTypes` | Öffentlich | SCIM-Ressourcentyp-Discovery |
| `GET` | `/api/v1/scim/v2/Users` | SCIM-Token | Benutzer auflisten, mit optionalem SCIM-Filter |
| `POST` | `/api/v1/scim/v2/Users` | SCIM-Token | Einen Benutzer erstellen |
| `GET` | `/api/v1/scim/v2/Users/:id` | SCIM-Token | Einen Benutzer abrufen |
| `PUT` | `/api/v1/scim/v2/Users/:id` | SCIM-Token | Einen Benutzer ersetzen |
| `DELETE` | `/api/v1/scim/v2/Users/:id` | SCIM-Token | Einen Benutzer soft deaktivieren |
| `GET` | `/api/v1/scim/v2/Groups` | SCIM-Token | Teams als SCIM-Gruppen auflisten |
| `POST` | `/api/v1/scim/v2/Groups` | SCIM-Token | Ein Team erstellen |
| `GET` | `/api/v1/scim/v2/Groups/:id` | SCIM-Token | Ein Team abrufen |
| `PUT` | `/api/v1/scim/v2/Groups/:id` | SCIM-Token | Ein Team und die Gruppenmitgliedschaft ersetzen |
| `DELETE` | `/api/v1/scim/v2/Groups/:id` | SCIM-Token | Ein Team löschen |

## Meme-Vorlagen {#meme-templates}

Unterstützende API für das Meme-Generator-Tool.

| Methode | Pfad | Zugriff | Beschreibung |
|--------|------|--------|-------------|
| `GET` | `/api/v1/meme-templates` | Auth | Alle verfügbaren Meme-Vorlagen mit Textfeld-Positionen auflisten |
| `GET` | `/api/v1/meme-templates/full/:filename` | Auth | Vollständiges Vorlagenbild bereitstellen |
| `GET` | `/api/v1/meme-templates/thumbs/:filename` | Auth | Vorlagen-Thumbnail bereitstellen |
| `GET` | `/api/v1/meme-templates/fonts/:filename` | Auth | Schriftdatei für das Rendering von Meme-Text bereitstellen |

## Fehlerantworten {#error-responses}

Alle Fehler geben JSON zurück:

```json
{
  "error": "Human-readable message",
  "code": "MACHINE_READABLE_CODE"
}
```

| Status | Bedeutung |
|--------|---------|
| 400 | Ungültige Anfrage / Validierung fehlgeschlagen |
| 401 | Nicht authentifiziert |
| 403 | Unzureichende Berechtigungen |
| 404 | Ressource nicht gefunden |
| 413 | Datei zu groß (siehe `MAX_UPLOAD_SIZE_MB`) |
| 422 | Verarbeitung nach der Validierung fehlgeschlagen |
| 429 | Ratenbegrenzt (siehe `RATE_LIMIT_PER_MIN`) |
| 501 | Erforderliches KI-Feature-Bundle ist nicht installiert (`FEATURE_NOT_INSTALLED`) |
| 500 | Interner Serverfehler |