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)
PUT/DELETE	/api/autosync/<id>	Ändern / 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

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, ?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)
DELETE	/api/history/<id>	Einzelnen Eintrag löschen
POST	/api/history/clear	Verlauf leeren (eigene Einträge; Admins leeren 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/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)

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-Session starten/beenden
GET	/api/stream/<token>/index.m3u8, /api/stream/<token>/segNNN.ts, /api/stream/<token>/status	HLS-Auslieferung
POST/GET	/api/progress/save, /api/progress/get, /api/progress/bulk	Abspielfortschritt

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