streamdock/docs/api.md

API-Referenz

StreamDock bietet eine RESTful JSON-API. Alle geschützten Endpunkte erfordern ein gültiges JWT-Token.

Authentifizierung

Geschützte Endpunkte erwarten eines der folgenden:

1. Header: Authorization: Bearer <token>
2. Cookie: streamdock_token=<token>
3. Query-Parameter: ?token=<token> (Fallback für Streaming/WebSocket)

---

Auth

Methode	Endpunkt	Auth	Beschreibung
POST	/api/auth/login	Nein	Anmeldung mit Benutzername & Passwort
GET	/api/auth/me	Ja	Eigenes Profil abrufen
PUT	/api/auth/me	Ja	Profil aktualisieren (Username, E-Mail)
PUT	/api/auth/me/password	Ja	Passwort ändern
POST	/api/auth/me/avatar	Ja	Profilbild hochladen (Multipart)

POST /api/auth/login

Request:

{
  "username": "admin",
  "password": "geheim"
}

Response (200):

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": 1,
    "username": "admin",
    "email": "admin@example.com",
    "role": "admin"
  }
}

---

Einstellungen

Methode	Endpunkt	Auth	Beschreibung
GET	/api/settings	Ja	Benutzer-Einstellungen abrufen
PUT	/api/settings	Ja	Einstellungen aktualisieren
PUT	/api/settings/volume	Ja	Lautstärke speichern (0-100)

---

Streams

Methode	Endpunkt	Auth	Beschreibung
GET	/api/streams	Ja	Alle Streams des Benutzers
POST	/api/streams	Ja	Neuen Stream hinzufügen
GET	/api/streams/{id}	Ja	Einzelnen Stream abrufen
PUT	/api/streams/{id}	Ja	Stream aktualisieren
DELETE	/api/streams/{id}	Ja	Stream löschen
POST	/api/streams/{id}/check	Ja	Stream-Verfügbarkeit prüfen
GET	/api/streams/{id}/now-playing	Ja	Aktuellen Titel abrufen (ICY-Metadata)
POST	/api/streams/metadata	Ja	Stream-Metadaten per URL parsen

POST /api/streams

Request:

{
  "name": "Mein Radiosender",
  "url": "https://stream.example.com/live",
  "stream_type": "audio"
}

GET /api/streams/{id}/now-playing

Response (200):

{
  "artist": "Interpret",
  "title": "Titel",
  "album": ""
}

---

Aufnahmen

Methode	Endpunkt	Auth	Beschreibung
GET	/api/recordings	Ja	Alle Aufnahmen des Benutzers
POST	/api/recordings/start	Ja	Aufnahme starten
POST	/api/recordings/{id}/stop	Ja	Aufnahme stoppen
GET	/api/recordings/{id}	Ja	Aufnahme-Details
DELETE	/api/recordings/{id}	Ja	Aufnahme löschen
GET	/api/recordings/{id}/download	Ja	Aufnahme herunterladen
GET	/api/recordings/{id}/stream	Ja	Aufnahme abspielen (Streaming)
POST	/api/recordings/{id}/share	Ja	Share-Link erstellen
POST	/api/recordings/{id}/plik	Ja	An Plik-Server senden

POST /api/recordings/start

Request:

{
  "stream_id": 5
}

Response (200):

{
  "id": 42,
  "status": "recording",
  "file_name": "Mein_Radiosender_20260412_200000.mp3"
}

POST /api/recordings/{id}/share

Request:

{
  "expires_hours": 72,
  "max_downloads": 10
}

Response (200):

{
  "token": "abc123...",
  "url": "http://localhost:8080/api/share/abc123.../download",
  "expires_at": "2026-04-15T20:00:00Z"
}

---

Zeitpläne

Methode	Endpunkt	Auth	Beschreibung
GET	/api/schedules	Ja	Alle Zeitpläne des Benutzers
POST	/api/schedules	Ja	Neuen Zeitplan erstellen
PUT	/api/schedules/{id}	Ja	Zeitplan aktualisieren
DELETE	/api/schedules/{id}	Ja	Zeitplan löschen

POST /api/schedules

Request (wiederkehrend):

{
  "stream_id": 5,
  "cron_expr": "0 0 20 * * 1-5",
  "duration": 3600,
  "is_recurring": true
}

Request (einmalig):

{
  "stream_id": 5,
  "start_time": "2026-04-15T20:00:00Z",
  "duration": 1800,
  "is_recurring": false
}

---

Bibliothek

Methode	Endpunkt	Auth	Beschreibung
GET	/api/library/search?q=rock	Ja	Volltextsuche über Streams & Aufnahmen
GET	/api/library/stats	Ja	Bibliotheksstatistiken

GET /api/library/stats

Response (200):

{
  "total_streams": 12,
  "total_recordings": 45,
  "active_recordings": 1,
  "storage_used": 1073741824
}

---

Sharing (öffentlich)

Diese Endpunkte erfordern keine Authentifizierung, nur einen gültigen Share-Token.

Methode	Endpunkt	Auth	Beschreibung
GET	/api/share/{token}	Nein	Metadaten der geteilten Aufnahme
GET	/api/share/{token}/download	Nein	Geteilte Aufnahme herunterladen
GET	/api/share/{token}/stream	Nein	Geteilte Aufnahme streamen

---

Radio-Browser

Methode	Endpunkt	Auth	Beschreibung
GET	/api/radio-browser/search?q=rock&country=DE	Nein	Radiosender suchen

Query-Parameter:

• q – Suchbegriff (Name)
• country – Länderfilter
• tag – Genre/Tag-Filter

---

Last.fm

Methode	Endpunkt	Auth	Beschreibung
GET	/api/lastfm/auth-url	Ja	OAuth-URL für Last.fm generieren
POST	/api/lastfm/callback	Ja	OAuth-Token von Last.fm übernehmen
POST	/api/lastfm/scrobble	Ja	Titel an Last.fm senden

---

Video-Proxy

Methode	Endpunkt	Auth	Beschreibung
POST	/api/proxy/start	Ja	RTMP→HLS Konvertierung starten
POST	/api/proxy/check	Ja	Prüfen ob Stream Proxy benötigt
DELETE	/api/proxy/{id}	Ja	Proxy-Session beenden
GET	/api/proxy/hls/{id}/{file}	Ja	HLS-Segmente ausliefern

---

Admin

Diese Endpunkte erfordern die Rolle admin.

Methode	Endpunkt	Auth	Beschreibung
GET	/api/admin/users	Admin	Alle Benutzer auflisten
POST	/api/admin/users	Admin	Neuen Benutzer erstellen
PUT	/api/admin/users/{id}	Admin	Benutzer bearbeiten
DELETE	/api/admin/users/{id}	Admin	Benutzer löschen (Kaskade)
PUT	/api/admin/users/{id}/quota	Admin	Speicher-Kontingent setzen

POST /api/admin/users

Request:

{
  "username": "neuer_user",
  "email": "user@example.com",
  "password": "sicheres-passwort",
  "role": "user",
  "storage_quota": 5368709120
}

---

Fehler-Responses

Alle API-Fehler folgen diesem Format:

{
  "error": "Beschreibung des Fehlers"
}

HTTP-Code	Bedeutung
400	Ungültige Anfrage
401	Nicht authentifiziert
403	Keine Berechtigung
404	Nicht gefunden
500	Interner Serverfehler

---

Weiter: Docker & Deployment