API Referenz DE

API-Referenz

🌐 English · Deutsch

Es gibt zwei API-Ebenen:

1. Externe REST-API (/api/v1/...) — für Skripte, Dashboards (z. B. Homepage/Homarr) und Drittsysteme. Authentifizierung per API-Key, kein Login nötig.
2. Interne API (/api/...) — wird von der WebUI verwendet, Session-basiert (Login erforderlich, teils Admin). Sie ist kein stabiler Vertrag, die wichtigsten Endpoints sind unten dennoch dokumentiert.

Externe API v1

Authentifizierung

API-Key im Header X-Api-Key mitsenden. Der Key wird beim ersten Start automatisch generiert und ist in Einstellungen → API einsehbar (dort auch neu generierbar).

curl -H "X-Api-Key: <key>" http://localhost:8080/api/v1/status

Fehlender/falscher Key → 401 Unauthorized.

Endpoints

Methode	Pfad	Beschreibung
GET	/api/v1/status	Gesamtstatus: Version, Pause-Status, Queue-Zähler nach Status, aktuell laufender Download inkl. Live-Fortschritt (episode_progress: percent, phase, speed, bandwidth; overall_progress_percent)
GET	/api/v1/queue	Alle Queue-Einträge; Filter: `?status=queued
GET	/api/v1/queue/<id>	Einzelner Queue-Eintrag (404 wenn unbekannt)
GET	/api/v1/library	Komplette Bibliothek (alle Pfade, Titel, Staffeln, Episoden, Größen)
GET	/api/v1/library/series	Nur Serien
GET	/api/v1/library/movies	Nur Filme
GET	/api/v1/stats	Download-Gesamtstatistiken

Beispiel: Status

{
  "version": "2.5.3",
  "paused": false,
  "queue": {"total": 12, "queued": 2, "running": 1, "completed": 8, "failed": 1, "cancelled": 0},
  "currently_running": {
    "id": 42, "title": "…", "current_episode": 3, "total_episodes": 12,
    "episode_progress": {"percent": 57, "phase": "download", "speed": "2.1x", "bandwidth": "8.4 MB/s", "active": true},
    "overall_progress_percent": 29
  }
}

Interne API (Auswahl)

Alle internen Endpoints erfordern eine eingeloggte Session; POST/PUT/DELETE verlangen Content-Type: application/json. Mit (Admin) markierte zusätzlich die Admin-Rolle.

Suche & Browse

Methode	Pfad	Beschreibung
POST	/api/search	`{keyword, site: "aniworld"
GET	/api/series / /api/seasons / /api/episodes	Serien-/Staffel-/Episodendaten zu einer URL
GET	/api/providers	Verfügbare Hoster/Sprachen einer Episode
GET	/api/new-animes, /api/popular-animes, /api/new-series, /api/popular-series, /api/new-movies, /api/random	Browse-Listen

Queue

Methode	Pfad	Beschreibung
POST	/api/download	Download-Auftrag anlegen
GET	/api/queue	Queue inkl. Fortschritt
POST	/api/queue/pause / /api/queue/resume	Globale Pause
POST	/api/queue/<id>/cancel / restart / skip-episode / retry-episode / move	Aktionen
DELETE	/api/queue/<id> / /api/queue/completed	Eintrag bzw. alle erledigten löschen

AutoSync

Methode	Pfad	Beschreibung
GET/POST	/api/autosync	Jobs auflisten / anlegen (Anlegen: Admin); Body u. a. language, provider, custom_path_id, episode_filter (JSON), movie_custom_path_id
POST	/api/autosync/site-search	Titel zu Kandidaten-Serien auf AniWorld/s.to auflösen (für „Zu Auto-Sync hinzufügen“ in der Bibliothek); Body {title}, liefert results[] mit site, site_label, title, url, score
PUT/DELETE	/api/autosync/<id>	Ändern (auch episode_filter, movie_custom_path_id, group_name) / löschen (Admin)
POST	/api/autosync/<id>/sync, /api/autosync/sync-all	Sofort synchronisieren
GET/POST	/api/autosync/export, /api/autosync/import, /api/autosync/batch	Sichern / Wiederherstellen / Mehrfach-Anlage. batch-Aktionen: enable, disable, set_path, set_group (+group_name), remove_group, delete
POST	/api/autosync/group/rename	Gruppe umbenennen; Body {old, new} — setzt group_name aller eigenen Jobs (Admin: aller) von old auf new

Kalender & Download-Verlauf

Methode	Pfad	Beschreibung
GET	/api/calendar	Aggregierte Kalender-Events des Benutzers (AutoSync + optionale Seerr-/Mediathek-Überlagerungen). Liefert events[], einen watcher-Statusblock (active, is_scanning, last_sync) und meta (seerr_active, seerr_count). Erfordert aktivierten Kalender + TMDB-Key.
GET	/api/history	Download-Verlauf; Query: ?search=, ?status=all|completed|failed|cancelled|skipped, ?source=all|manual|autosync|seerr, ?range=all|1d|7d|30d, ?limit= (max 200), ?offset=. Benutzer sehen eigene Einträge, Admins alle. Liefert entries[] + total.
GET	/api/history/<id>	Einzelner Verlaufseintrag (403, wenn nicht eigener und kein Admin)
GET	/api/history/export	Gefilterte Ansicht exportieren; ?format=csv|json plus dieselben Filter wie /api/history
POST	/api/history/<id>/retry	Fehlgeschlagene/abgebrochene Episode erneut einreihen
DELETE	/api/history/<id>	Einzelnen Eintrag löschen
POST	/api/history/delete	Mehrere Einträge löschen (Body {ids: [...]})
POST	/api/history/clear	Verlauf leeren; Body kann status/source/range/search enthalten → nur gefilterte Teilmenge wird gelöscht (sonst alles; eigene Einträge, Admins alle)

Einstellungen (Admin)

Methode	Pfad	Beschreibung
GET/PUT	/api/settings	Allgemeine Einstellungen
GET/PUT	/api/settings/sso, /api/settings/cineinfo, /api/settings/mediaplayer, /api/settings/mediascan, /api/settings/seerr, /api/settings/crunchyroll, /api/settings/dns	Teilbereiche
GET/POST	/api/settings/api-key, /api/settings/api-key/regenerate	Externer API-Key
GET/POST	/api/encoding/settings, /api/encoding/detect-hw	Encoding
GET/POST	/api/upscale/settings, …	Upscaling (Settings lesen ist für alle erlaubt)

Crunchyroll

Methode	Pfad	Beschreibung
GET/PUT	/api/settings/crunchyroll	Einstellungen laden/speichern (Passwort nur schreibend; clear_password: true vergisst es)
POST	/api/settings/crunchyroll/test	Login prüfen → {ok, mode, profile, premium}
GET	/api/settings/crunchyroll/profiles	Konto-Profile für die Auswahl auflisten
GET	/api/crunchyroll/availability?title=…	Ob ein Titel auf Crunchyroll ist (Provider-Pill; 24 h Cache)

Basiert auf web/crunchyroll_service.py — ein thread-sicherer Client-Cache (6 h Re-Login-TTL, verschlüsselte Session-Token-Datei, fehlertolerant) auf dem gebündelten Client vendor/crunchyroll_api.py. Der anonyme Modus braucht kein Konto; Watchlist/Profil und Premium-Prüfung erfordern einen Login. Der Kalender nutzt get_simulcast_titles() / get_watchlist_titles() (Crunchyroll weiß welche Anime; TMDB liefert die Termine). Videostreams sind DRM-geschützt und werden nie heruntergeladen.

Bibliothek & Player

Methode	Pfad	Beschreibung
GET	/api/library / /api/library/status / /api/library/watcher	Bestand & Scan-Status
POST	/api/library/refresh (Admin), /api/library/delete (Admin), /api/library/rename (Admin), /api/library/move (Admin), /api/library/media_info	Verwaltung
POST	/api/stream/start / /api/stream/stop	HLS-Transcode-Session starten/beenden (Bibliotheksdateien)
GET	/api/stream/<token>/index.m3u8, /api/stream/<token>/segNNN.ts, /api/stream/<token>/status	HLS-Auslieferung
POST	/api/stream/start-source	Episode direkt vom Provider per Transcode streamen; Body {episode_url, provider, language, start_pos}
POST	/api/stream/start-proxy / /api/stream/close-proxy	Passthrough-Proxy-Session für die native Provider-HLS starten/beenden (kein FFmpeg); liefert {token, playlist_url, hls}
GET	/api/proxy/<token>/r/<b64url>	Provider-Playlist (umgeschrieben) bzw. Segment/Key (durchgeleitet) proxen; leitet Range weiter. SSRF-geschützt (nur http/https, private/Loopback-Hosts blockiert)
POST/GET	/api/progress/save, /api/progress/get, /api/progress/bulk	Abspielfortschritt (pro Benutzer)

Syncplay & Web-Konsole

Methode	Pfad	Beschreibung
GET	/api/syncplay/config	Ob ein Syncplay-Server konfiguriert ist
POST	/api/syncplay/join / /api/syncplay/leave	Raum betreten/verlassen (Server öffnet einen echten Syncplay-Client); Body {room, username?}
POST	/api/syncplay/control / /api/syncplay/report	Play/Pause/Seek senden; aktuelle Position melden (Heartbeat)
GET	/api/syncplay/poll	Maßgebliche Status-Events + Raum-Nutzerliste abfragen (?session_id=&after=)
GET	/api/console (Admin)	Schreibgeschützter Live-Konsolenpuffer; ?after=<seq> für inkrementelles Polling (nur wenn Web-Konsole aktiviert)

Sonstiges

Methode	Pfad	Beschreibung
GET	/api/captcha/<queue_id>/screenshot / status; POST /api/captcha/<queue_id>/click	Interaktive Captcha-Lösung
GET/POST	/api/notif/settings, /api/notif/user-settings, /api/notif/admin-settings, /api/notif/test	Benachrichtigungen
GET	/api/seerr/requests; POST …/approve, …/decline, …/hide	Seerr-Anfragen
GET/POST	/api/update-check	Update-Prüfung
GET/POST/DELETE	/api/favourites	Favoriten
GET	/api/stats, /api/stats/queue, /api/stats/sync, /api/stats/general	Statistiken