stream-recorder/docs/api.md

REST-API

Alle Funktionen des Web-UI sind auch per REST-API verfügbar. Basis-URL: http://<host>:8484

Die interaktive API-Dokumentation (Swagger-UI unter /docs) ist standardmäßig deaktiviert und kann mit der Umgebungsvariable ENABLE_API_DOCS=1 eingeschaltet werden.

Endpunkte

System

Methode	Pfad	Beschreibung
GET	/api/health	Health Check (kein Auth nötig)
GET	/api/config	Konfiguration lesen (ohne Secrets)
PUT	/api/config	Konfiguration speichern (siehe Konfiguration)

Jobs

Methode	Pfad	Beschreibung
GET	/api/jobs	Alle Jobs auflisten
POST	/api/jobs	Neuen Job erstellen
GET	/api/jobs/:id	Job-Details abrufen
PUT	/api/jobs/:id	Job aktualisieren
DELETE	/api/jobs/:id	Job löschen (nicht während einer laufenden Aufnahme → 400)
POST	/api/jobs/:id/record	Job-Aufnahme starten (läuft bereits → 409)

Senderbibliothek

Methode	Pfad	Beschreibung
GET	/api/stations	Alle gespeicherten Sender auflisten
POST	/api/stations	Neuen Sender erstellen
GET	/api/stations/:id	Sender-Details abrufen
PUT	/api/stations/:id	Sender aktualisieren
DELETE	/api/stations/:id	Sender löschen (verknüpfte Jobs werden gelöst)

Schnellaufnahme

Methode	Pfad	Beschreibung
POST	/api/quick-record	Schnellaufnahme starten

{
    "url": "rtmp://example.com/live/stream",
    "name": "Meine Aufnahme",
    "stream_type": "auto",
    "max_duration": 3600
}

Erlaubte URL-Schemata: http, https, rtmp, rtmps, rtsp, rtsps. Für Job-Felder gelten dieselben Prüfungen wie im Web-UI (siehe Jobs).

Aufnahmen

Methode	Pfad	Beschreibung
GET	/api/recordings	Alle Aufnahmen (Parameter: active_only, limit)
GET	/api/recordings/:id	Aufnahme-Status
POST	/api/recordings/:id/stop	Aufnahme stoppen
POST	/api/recordings/:id/extend?minutes=30	Aufnahme verlängern (minutes 1–1440; bei unbegrenzter Aufnahme → 400)
POST	/api/recordings/:id/unlimited	Zeitlimit entfernen

Logs

Methode	Pfad	Beschreibung
GET	/api/logs	Protokoll (Parameter: limit, level)

Zeitstempel in API-Antworten sind UTC mit Offset, z.B. 2026-10-11T14:30:00+00:00.

Konfiguration

GET /api/config liefert keine Secrets. Stattdessen zeigen boolesche Felder an, ob ein Wert gesetzt ist:

Feld	Bedeutung
auth.password_set	Passwort ist gesetzt
ntfy.token_set	NTFY-Token ist gesetzt
plik.api_key_set	Plik-API-Key ist gesetzt

Regeln für PUT /api/config:

• Secret-Felder (auth.password, ntfy.token, plik.api_key) weglassen = unverändert
• Leerer String "" = Secret entfernen (nicht beim Passwort)
• auth.enabled: true erfordert ein Passwort (mind. 8 Zeichen)
• download_path muss innerhalb von RECORDING_ROOTS liegen
• Unbekannte Schlüssel → 422
• Der Abschnitt server kann nicht über die API geändert werden

curl -u admin:passwort -X PUT http://localhost:8484/api/config   -H "Content-Type: application/json"   -d '{"ntfy": {"url": "https://ntfy.sh/mein-topic", "events": "start,error"}}'

Authentifizierung

Bei aktiviertem Auth (Standard bei Neuinstallationen) wird Basic Authentication verwendet:

curl -u admin:passwort http://localhost:8484/api/jobs

• Der Health-Endpunkt (/api/health) ist immer ohne Auth erreichbar.
• Nach 10 fehlgeschlagenen Logins innerhalb von 5 Minuten antwortet der Server für diese IP bis zum Ende des Zeitfensters mit 429.

Browser-Zugriff

CORS ist nicht aktiviert. Schreibende Requests (POST, PUT, DELETE) mit fremdem Origin werden mit 403 abgewiesen. Die API ist damit aus Skripten/curl (ohne Origin-Header) und aus dem eigenen Web-UI nutzbar, nicht aber von fremden Webseiten.

Fehlercodes

Fehler werden als JSON mit Feld detail zurückgegeben.

Code	Bedeutung
400	Ungültige Anfrage, Meldung auf Deutsch (z.B. nicht erlaubte ffmpeg-Argumente, unzulässiger Pfad)
401	Anmeldung erforderlich oder fehlgeschlagen
403	Cross-Site-Request abgewiesen
404	Objekt nicht gefunden
409	Konflikt, z.B. Job nimmt bereits auf
422	Validierungsfehler (ungültige Felder, unbekannte Schlüssel)
429	Zu viele fehlgeschlagene Logins