ripster/docs/api/settings.md

Settings API

Endpunkte zum Lesen und Schreiben der Anwendungseinstellungen.

---

GET /api/settings

Gibt alle Einstellungen kategorisiert zurück.

Response:

{
  "paths": {
    "raw_dir": {
      "value": "/mnt/nas/raw",
      "schema": {
        "type": "string",
        "label": "Raw-Verzeichnis",
        "description": "Speicherort für rohe MKV-Dateien",
        "required": true
      }
    },
    "movie_dir": {
      "value": "/mnt/nas/movies",
      "schema": { ... }
    }
  },
  "tools": { ... },
  "encoding": { ... },
  "drive": { ... },
  "makemkv": { ... },
  "omdb": { ... },
  "notifications": { ... }
}

---

PUT /api/settings/:key

Aktualisiert eine einzelne Einstellung.

URL-Parameter: key – Einstellungs-Schlüssel

Request:

{
  "value": "/mnt/storage/raw"
}

Response:

{ "ok": true, "key": "raw_dir", "value": "/mnt/storage/raw" }

Fehlerfälle:

• 400 – Ungültiger Wert (Validierungsfehler)
• 404 – Einstellung nicht gefunden

!!! note "Encode-Review-Refresh" Wenn eine encoding-relevante Einstellung geändert wird (z.B. handbrake_preset), wird der Encode-Plan für den aktuell wartenden Job automatisch neu berechnet.

---

PUT /api/settings

Aktualisiert mehrere Einstellungen auf einmal.

Request:

{
  "raw_dir": "/mnt/storage/raw",
  "movie_dir": "/mnt/storage/movies",
  "handbrake_preset": "H.265 MKV 720p30"
}

Response:

{
  "ok": true,
  "updated": ["raw_dir", "movie_dir", "handbrake_preset"],
  "errors": []
}

---

POST /api/settings/pushover/test

Sendet eine Test-Benachrichtigung über PushOver.

Request: Kein Body erforderlich (verwendet gespeicherte Zugangsdaten)

Response (Erfolg):

{ "ok": true, "message": "Test-Benachrichtigung gesendet" }

Response (Fehler):

{ "ok": false, "error": "Ungültiger API-Token" }

---

Skript-Verwaltung

Skripte werden über eigene Endpunkte unter /api/settings/scripts verwaltet. Jedes Skript hat eine scriptBody-Property (der Shell-Befehl oder mehrzeiliges Skript) und einen orderIndex für die Sortierung.

GET /api/settings/scripts

Gibt alle Skripte zurück, sortiert nach orderIndex.

Response:

{
  "scripts": [
    {
      "id": 1,
      "name": "Zu Plex verschieben",
      "scriptBody": "mv \"$RIPSTER_OUTPUT_PATH\" /mnt/plex/movies/",
      "orderIndex": 1,
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

---

POST /api/settings/scripts

Legt ein neues Skript an.

Request:

{
  "name": "Zu Plex verschieben",
  "scriptBody": "mv \"$RIPSTER_OUTPUT_PATH\" /mnt/plex/movies/"
}

Feld	Typ	Pflicht	Beschreibung
name	string	✅	Anzeigename (eindeutig)
scriptBody	string	✅	Shell-Befehl oder mehrzeiliges Skript

Response: 201 Created – { "script": { ... } }

---

PUT /api/settings/scripts/:id

Aktualisiert ein vorhandenes Skript. Alle Felder optional.

---

DELETE /api/settings/scripts/:id

Löscht ein Skript.

!!! warning "Referenzen" Das Skript wird gelöscht, auch wenn es in Job-Historien referenziert ist. In zukünftigen Reviews erscheint es nicht mehr.

---

POST /api/settings/scripts/:id/test

Führt ein Skript mit Platzhalter-Umgebungsvariablen aus (Testlauf).

Response:

{
  "ok": true,
  "exitCode": 0,
  "stdout": "Testausgabe des Skripts",
  "stderr": "",
  "durationMs": 245
}

Platzhalter-Werte beim Testlauf:

Variable	Testwert
RIPSTER_OUTPUT_PATH	/tmp/ripster-test-output.mkv
RIPSTER_JOB_ID	0
RIPSTER_TITLE	Test Film
RIPSTER_YEAR	2024
RIPSTER_IMDB_ID	tt0000000
RIPSTER_RAW_PATH	/tmp/ripster-test-raw.mkv

---

POST /api/settings/scripts/reorder

Ändert die Reihenfolge der Skripte (persistiert in order_index).

Request:

{ "orderedScriptIds": [3, 1, 2] }

Response: { "scripts": [ ... ] } – alle Skripte in neuer Reihenfolge.

---

Skript-Ketten-Verwaltung

Skript-Ketten werden unter /api/settings/script-chains verwaltet.

GET /api/settings/script-chains

Gibt alle Ketten zurück (inkl. Schritte).

POST /api/settings/script-chains

Legt eine neue Kette an.

{ "name": "Nach Jellyfin deployen" }

PUT /api/settings/script-chains/:id

Aktualisiert eine Kette (Name, Schritte).

DELETE /api/settings/script-chains/:id

Löscht eine Kette und alle ihre Schritte.

POST /api/settings/script-chains/:id/test

Führt eine Kette mit Platzhalter-Umgebungsvariablen aus (Testlauf).

Response:

{
  "result": {
    "success": true,
    "steps": [
      { "scriptId": 1, "scriptName": "Zu Plex verschieben", "success": true, "exitCode": 0 }
    ]
  }
}

POST /api/settings/script-chains/reorder

Ändert die Reihenfolge der Ketten (persistiert in order_index).

Request:

{ "orderedChainIds": [2, 1, 3] }

---

User-Presets

Benannte HandBrake-Preset-Sammlungen, die im Encode-Review schnell angewendet werden können. Unter /api/settings/user-presets verwaltet.

GET /api/settings/user-presets

Gibt alle User-Presets zurück. Optional gefiltert per Query-Parameter mediaType.

Query-Parameter:

Parameter	Werte	Beschreibung
mediaType	bluray, dvd, other, all	Filtert Presets nach Medientyp

Response:

{
  "presets": [
    {
      "id": 1,
      "name": "Blu-ray High Quality",
      "mediaType": "bluray",
      "handbrakePreset": "H.265 MKV 1080p30",
      "extraArgs": "--encoder-preset slow",
      "description": "Langsam, aber beste Qualität",
      "createdAt": "2026-01-15T10:00:00.000Z",
      "updatedAt": "2026-01-15T10:00:00.000Z"
    }
  ]
}

---

POST /api/settings/user-presets

Legt ein neues User-Preset an.

Request:

{
  "name": "Blu-ray High Quality",
  "mediaType": "bluray",
  "handbrakePreset": "H.265 MKV 1080p30",
  "extraArgs": "--encoder-preset slow",
  "description": "Langsam, aber beste Qualität"
}

Feld	Typ	Pflicht	Beschreibung
name	string	✅	Anzeigename
mediaType	string	—	bluray, dvd, other, all (Standard: all)
handbrakePreset	string	—	HandBrake-Preset-Name (-Z)
extraArgs	string	—	Zusatz-CLI-Argumente
description	string	—	Optionale Beschreibung

Response: 201 Created – { "preset": { ... } }

---

PUT /api/settings/user-presets/:id

Aktualisiert ein User-Preset. Alle Felder optional.

---

DELETE /api/settings/user-presets/:id

Löscht ein User-Preset.

---

Einstellungs-Schlüssel Referenz

Eine vollständige Übersicht aller Schlüssel: :octicons-arrow-right-24: Einstellungsreferenz