HTTP-API

Konventionen

Anfrage- und Antwortkörper sind JSON. Endpunkte, die einen Body erwarten, verlangen Content-Type: application/json. Die Basis-URL auf dieser gesamten Seite ist http://headend.local:8080; setzen Sie Ihre Adresse und den mit --port konfigurierten Port ein.

Senderkennungen in Pfaden sind die numerische id aus der Konfigurationsdatei. Sie werden nach einem Löschen wiederverwendet; ein Skript, das eine Kennung über eine Neukonfiguration hinweg zwischenspeichert, kann daher auf den falschen Sender wirken.

Authentifizierung

Methode	Pfad	Zweck
GET	/login	Die Login-Seite selbst. Für ein Skript nutzlos; aufgeführt, damit eine unerwartete HTML-Antwort auf einen API-Aufruf als Umleitung dorthin erkennbar ist.
POST	/api/login	Tauscht Benutzername und Passwort gegen ein Session-Cookie. Die Zugangsdaten sind die Werte von CASTMUX_WEB_USERNAME und CASTMUX_WEB_PASSWORD.
POST	/api/logout	Macht die aktuelle Session ungültig.

Mit curl speichern Sie das Cookie beim Login in einer Cookie-Datei und übergeben diese danach:

# log in, keeping the session cookie
curl -s -c cookies.txt \
     -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"correct-horse-battery"}' \
     http://headend.local:8080/api/login

# now call an authenticated endpoint with the same jar
curl -s -b cookies.txt \
     http://headend.local:8080/api/viewers

Sessions, keine Tokens

API-Tokens gibt es derzeit nicht. Eine dauerhaft laufende Integration muss sich anmelden, das Cookie behalten und sich nach Ablauf der Session erneut anmelden. Token-Authentifizierung ist geplant.

Öffentliche Endpunkte

Methode	Pfad	Zweck
GET	/api/version	Version, Commit und Build-Zeitpunkt des laufenden Binarys. Bewusst ohne Authentifizierung, damit ein Monitoring-System auf jedem Gerät eines Bestands prüfen kann, was installiert ist, ohne Zugangsdaten zu erhalten, mit denen es dort etwas ändern könnte.

curl -s http://headend.local:8080/api/version
# {"version":"3.1.0","commit":"9f2c41a","built":"2026-04-08T09:12:44Z"}

Nur über Loopback

Methode	Pfad	Zweck
POST	/api/internal/streams/{id}/restart	Startet einen Sender neu, für einen Supervisor, der auf dem Gerät selbst läuft. Der optionale Parameter ?reason= wird ins Log geschrieben, sodass ein Neustart dort seinen Anlass nennt. Zurückgegeben werden der Name des Senders und ob eine laufende Engine neu gestartet wurde. Der mitgelieferte Watchdog nutzt ihn, um einen hängenden Sender wiederherzustellen, ohne den ganzen Container neu zu starten und damit jeden gesunden Sender vom Netz zu nehmen.

Dieser Endpunkt erfordert keine Anmeldung. Stattdessen weist er jede Verbindung, die nicht von einer Loopback-Adresse (127.0.0.1 oder ::1) kommt, mit 403 und einer Log-Zeile ab, die den Aufrufer nennt. So muss das Admin-Passwort nicht in einer Datei auf der Festplatte liegen, damit der Watchdog es lesen kann. Um den Endpunkt zu erreichen, braucht man ohnehin bereits eine Shell auf dem Gerät.

Leiten Sie den Web-Port nicht vom selben Host aus per Proxy weiter

Castmux läuft mit Host-Networking, daher sieht die Loopback-Prüfung alles, was sich auf dem Gerät selbst verbindet. Ein Reverse-Proxy auf dem Gerät, der an 127.0.0.1:8080 weiterleitet, ließe jede weitergereichte Anfrage lokal erscheinen. Jeder, der den Proxy erreicht, könnte dann ohne Anmeldung Sender neu starten. Betreiben Sie einen Proxy auf einem anderen Rechner, oder lassen Sie ihn /api/internal/ sperren.

Sender

Methode	Pfad	Zweck
Lebenszyklus
POST	/api/channels	Legt einen Sender an. Der Body hat dieselbe Struktur wie ein Eintrag unter streams in der Konfigurationsdatei. Die zugewiesene Kennung wird zurückgegeben.
PUT	/api/channels/{id}	Ersetzt die Einstellungen eines bestehenden Senders. Ein laufender Sender wird neu gestartet, wenn die Änderung seinen Betrieb betrifft.
DELETE	/api/channels/{id}	Entfernt einen Sender, nachdem er zuvor gestoppt wurde. Die Kennung wird zur Wiederverwendung frei.
POST	/api/channels/{id}/restart	Startet einen Sender neu, ohne die anderen anzurühren. Der erste Versuch, wenn ein einzelner Sender Probleme macht und die übrigen gesund sind.
Zustand
POST	/api/streams/{id}/active	Aktiviert oder deaktiviert einen Sender. Ein deaktivierter Sender behält seine Konfiguration, wird aber nie gestartet.
POST	/api/streams/{id}/force-always-on	Schaltet das Always-on-Override um. Eingeschaltet läuft der Sender dauerhaft; ausgeschaltet läuft er, wenn die Zuschauererkennung jemanden zuschauen sieht.
Abfrage
GET	/api/channels	Eine kurze Liste aller Sender: id, name, Ziel-address und -port sowie epg_id. Genug, um herauszufinden, welche Sender existieren. Die vollständigen Einstellungen eines Senders — Quelle, Engine, Profil, Überwachung — werden nicht zurückgegeben; ein Skript, das diese braucht, liest die Konfigurationsdatei.
GET	/api/channels/{id}/ts-quality	Qualität des Transportstroms für einen Sender: der neueste Messwert, laufende Summen der Continuity-, Transport- und PCR-Fehler sowie die letzten 30 Minuten Verlauf in 5-Sekunden-Intervallen. Gibt außerdem an, ob die Überwachung für den Sender läuft und wie sein PCR-Timing gemessen wird. Siehe Qualität des Transportstroms.
GET	/api/channels/{id}/logs	Aktuelle Engine-Ausgaben eines Senders. Hier erscheint ein Quellfehler in dem Wortlaut, den der Ursprungsserver tatsächlich verwendet hat, statt als allgemeiner Fehler.
GET	/api/channels/resolutions	Die derzeit für jeden Sender gewählte Auflösung und ob sie exakt dem angeforderten Profil entspricht oder die nächstliegende Stufe ist, die der Ursprungsserver anbot. Aus dem Cache geliefert; blockiert nicht auf Abrufe beim Ursprungsserver.
Vorschau
POST	/api/channels/{id}/preview	Startet eine im Browser ansehbare Vorschau eines Senders.
POST	/api/channels/{id}/preview/stop	Beendet sie. Vorschauen verbrauchen echte CPU-Leistung; beenden Sie sie daher ausdrücklich, statt sich auf das Schließen der Seite zu verlassen.

# create a channel
curl -s -b cookies.txt -X POST \
     -H 'Content-Type: application/json' \
     -d '{
       "name": "Example One",
       "description": "Main lounge line-up",
       "active": true,
       "force_always_on": false,
       "engine": "tsduck",
       "resolution_profile": "hd",
       "source":      {"type": "hls", "url": "https://origin.example.net/one/master.m3u8"},
       "destination": {"address": "239.10.0.1", "port": 5000}
     }' \
     http://headend.local:8080/api/channels

Programmführer

Methode	Pfad	Zweck
Quellen
POST	/api/epg/sources	Fügt eine XMLTV-Quelle hinzu. Body: {"name": "...", "url": "..."}. Gibt die id der neuen Quelle zurück. Die Senderliste der Quelle wird im Hintergrund abgerufen.
PUT	/api/epg/sources/{id}	Benennt eine Quelle um oder richtet sie auf eine neue URL, mit demselben Body. Gespeicherte Daten bleiben erhalten und werden bei der nächsten Synchronisierung ersetzt.
DELETE	/api/epg/sources/{id}	Entfernt eine Quelle und ihre gespeicherten Programmdaten. Ihr zugeordnete Sender behalten ihre epg_id.
POST	/api/epg/sources/{id}/sync	Ruft die Quelle sofort ab und speichert die Sendungen für zugeordnete Sender. Synchron: Die Antwort meldet das tatsächliche Ergebnis, und bei einem großen Programmführer kann das Minuten dauern.
Zuordnung und Daten
GET	/api/epg/channels	Jede Quelle, nach ihrer id geschlüsselt, mit Name, URL, letztem Abruf und Status sowie den Programmführer-Kennungen, die sie anbietet.
POST	/api/epg/map	Ordnet einen Sender einer Programmführer-Kennung zu. Body: {"stream_id": 3, "tvg_id": "rtl.de"}. Eine leere tvg_id hebt die Zuordnung auf. Gespeichert in der epg_id des Senders.
GET	/api/epg/now	Was jetzt und was als Nächstes läuft, für jeden zugeordneten Sender in einem Aufruf. Ein zugeordneter Sender, auf dem gerade nichts läuft, ist mit leerem now enthalten — im Unterschied zu einem nicht zugeordneten Sender, der fehlt.

Lizenz

Methode	Pfad	Zweck
GET	/api/licence	Der Lizenzstatus des Geräts: state mit lesbarer message und detail, can_stream, der device_code, nach dem der Support fragen wird, und ein Support-contact. Hat die letzte Synchronisierung vom Lizenzserver gesendete Sender abgelehnt, sind auch die Gründe enthalten. Das Lizenz-Token selbst wird nie zurückgegeben.
POST	/api/licence/retry	Meldet das Gerät sofort beim Lizenzserver an, statt auf den nächsten geplanten Versuch zu warten. Verwenden Sie das, nachdem Sie behoben haben, was die Lizenz blockiert hat, etwa ein abgelaufenes Abonnement oder eine Firewall-Regel. Der Aufruf kehrt sofort zurück; fragen Sie das Ergebnis über /api/licence ab.

Zuschauer

Methode	Pfad	Zweck
GET	/api/viewers	Zuschauerstatus aller Sender in einem Aufruf. Verwenden Sie das zum Pollen, statt über die Sender zu iterieren, was die Zahl der Anfragen mit der Größe der Senderliste multipliziert.
GET	/api/streams/{id}/viewers	Details zu einem Sender: die Liste der aktuell beigetretenen Client-Adressen, deren Anzahl, ein Flag, ob im Segment ein IGMP-Querier vorhanden ist, und ein Flag, ob die Erkennung eingeschränkt ist.

Warum es ein Flag „degraded“ gibt

Eine Zuschauerzahl von null hat zwei völlig verschiedene Bedeutungen: Niemand schaut zu, oder wir können es gerade nicht feststellen. Der zweite Fall tritt ein, wenn der Paketmitschnitt nicht starten kann, die Mitschnitt-Schnittstelle verschwindet oder kein Querier existiert und sich seit dem letzten Neustart niemand gemeldet hat. Beides als 0 zu melden, würde einen Alarm auf „keine Zuschauer“ bei einem Monitoring-Fehler auslösen und — schlimmer — eine tatsächliche Abwesenheit von Zuschauern ununterscheidbar von einer blinden Kopfstation machen. Verstehen Sie degraded als „diese Zahl ist kein Beleg“, und beachten Sie, dass die Sender bei aktiviertem on_demand_fail_open trotzdem weiterstreamen.

Metriken und System

Methode	Pfad	Zweck
Messung
GET	/api/metrics	System- und Sendermetriken in einem Dokument: CPU, Speicher, Laufzeit, Zustand und Durchsatz pro Sender. Serverseitig etwa zwei Sekunden zwischengespeichert; schnelleres Pollen liefert dieselben Zahlen und kostet nur Anfrageverarbeitung.
GET	/api/network-stats	Zähler auf Schnittstellenebene und Erreichbarkeitsergebnisse für die Hosts in ping_hosts.
GET	/api/udp-bitrate	Gemessene Bitrate, die den Netzwerkport tatsächlich verlässt, pro Sender. Das ist das von der Engine unabhängige Lebenszeichen: Es spiegelt wider, was auf der Leitung ist, nicht, was ein Decoder zu erzeugen behauptet.
Administration
PUT	/api/settings	Ändert global-Einstellungen. Senden Sie nur die zu ändernden Schlüssel; alles Ausgelassene behält seinen aktuellen Wert. Nur PUT — eine GET-Variante gibt es nicht; lesen Sie die aktuellen Einstellungen daher aus der Konfigurationsdatei.
GET	/api/network-interfaces	Jede IPv4-Adresse des Geräts, zur Wahl von udp_device: Adresse, Schnittstelle, ob die Schnittstelle aktiv ist, ihr Subnetz und ob die Adresse per DHCP vergeben wurde. Loopback- und Link-Local-Adressen werden weggelassen, weil keine von beiden je die richtige Wahl ist. Inaktive Schnittstellen werden aufgeführt, nicht ausgeblendet, weil eine inaktive Schnittstelle genau das ist, was Sie sehen müssen.
POST	/api/restart-all	Startet jeden Sender neu. Die Starts werden um startup_stagger_seconds gestaffelt, damit nicht die gesamte Senderliste auf einmal zurückkommt und gemeinsam scheitert.
POST	/api/restart-app	Startet die Castmux-Anwendung neu. Sie antwortet zuerst, fährt dann sauber herunter, und die Restart-Policy des Containers startet sie innerhalb weniger Sekunden wieder. Jeder Sender ist kurz nicht auf Sendung. Anders als /api/reboot braucht der Aufruf nichts auf dem Host und funktioniert daher in jeder Container-Umgebung.
POST	/api/reboot	Startet das Gerät neu. Jeder Sender ist für die gesamte Dauer nicht auf Sendung; das ist kein Mittel gegen einen Senderfehler.

DVB-C-Multiplexe

Methode	Pfad	Zweck
Multiplexe
GET	/api/dvb/muxes	Listet die konfigurierten Multiplexe mit ihren HF-Parametern und ihrem aktuellen Zustand auf. Anders als für Sender gibt es für Multiplexe einen Lese-Endpunkt.
POST	/api/dvb/muxes	Legt einen Multiplex an.
PUT	/api/dvb/muxes/{id}	Aktualisiert HF-Parameter oder Signalisierungskennungen. Eine Änderung von Frequenz, Modulation oder Symbolrate unterbricht den Träger.
DELETE	/api/dvb/muxes/{id}	Entfernt einen Multiplex. Die darin geführten Sender werden nicht gelöscht.
POST	/api/dvb/muxes/{id}/active	Startet oder stoppt die Ausstrahlung des Trägers.
Inhalte und Vorgänge
POST	/api/dvb/muxes/{id}/channels	Weist die geführten Sender und ihre Reihenfolge zu. Die Reihenfolge bestimmt die Service-IDs; eine Umsortierung vergibt den Diensten daher neue Kennungen und kann einen neuen Sendersuchlauf der Fernseher erfordern. Hängen Sie an, statt einzufügen, wo Sie die Wahl haben.
GET	/api/dvb/muxes/{id}/logs	Ausgaben von Multiplexer und Modulator für diesen Träger.
POST	/api/dvb/muxes/{id}/hot-swap	Tauscht die Inhalte eines laufenden Multiplex aus, ohne den Träger abzuschalten, sodass die Geräte eingestellt bleiben, statt während der Änderung „kein Signal“ zu melden.
POST	/api/dvb/muxes/{id}/suspend	Setzt den Multiplex vorübergehend aus, für Wartungsarbeiten am Modulator oder am Kabelnetz, ohne die Konfiguration zu löschen.

HDMI-Ausgabe

Methode	Pfad	Zweck
POST	/api/hdmi/active	Aktiviert oder deaktiviert die HDMI-Ausgabe.
POST	/api/hdmi/config	Legt fest, welcher Sender am HDMI-Port ausgegeben und wie er dargestellt wird.
GET	/api/hdmi/outputs	Was dieses Gerät ansteuern kann: vos (Videotreiber), drm_devices (Anzeigegeräte) und audio_devices (jeweils mit value und label, so wie der Player selbst sie auflistet) sowie die aktuelle Auswahl current. Die Werte sind genau das, was /api/hdmi/config akzeptiert.
GET	/api/hdmi/metrics	Zustand und Durchsatz der HDMI-Ausgabe.
GET	/api/hdmi/logs	Ausgaben des HDMI-Wiedergabeprozesses.

Einrichtung eines Standorts automatisieren

Ein durchgearbeitetes Beispiel: anmelden, drei Sender anlegen, einen Multiplex anlegen und ihm die Sender in der Reihenfolge zuweisen, in der sie erscheinen sollen. Das ist die gesamte Inbetriebnahme eines kleinen Standorts, und es lohnt sich, sie zu skripten, denn beim Eintippen von drei Sendern in ein Formular entstehen vertauschte Multicast-Adressen.

#!/usr/bin/env bash
set -euo pipefail

BASE="http://headend.local:8080"
JAR="$(mktemp)"

# 1. log in ------------------------------------------------------------
curl -sf -c "$JAR" -H 'Content-Type: application/json' \
     -d "{\"username\":\"$CASTMUX_USER\",\"password\":\"$CASTMUX_PASS\"}" \
     "$BASE/api/login" > /dev/null

# 2. create the channels ------------------------------------------------
#    name | multicast group | source playlist
CHANNELS=(
  "Example One|239.10.0.1|https://origin.example.net/one/master.m3u8"
  "Example Two|239.10.0.2|https://origin.example.net/two/master.m3u8"
  "Example News|239.10.0.3|https://origin.example.net/news/master.m3u8"
)

IDS=()
for row in "${CHANNELS[@]}"; do
  IFS='|' read -r NAME GROUP URL <<< "$row"

  ID=$(curl -sf -b "$JAR" -X POST -H 'Content-Type: application/json' \
    -d "{
          \"name\": \"$NAME\",
          \"active\": true,
          \"force_always_on\": true,
          \"engine\": \"tsduck\",
          \"resolution_profile\": \"hd\",
          \"source\":      {\"type\": \"hls\", \"url\": \"$URL\"},
          \"destination\": {\"address\": \"$GROUP\", \"port\": 5000}
        }" \
    "$BASE/api/channels" | sed -n 's/.*"id":\([0-9]*\).*/\1/p')

  echo "created $NAME as id $ID"
  IDS+=("$ID")

  # respect the stagger: three HLS origins opened at once is the
  # failure this setting exists to prevent
  sleep 3
done

# 3. create the multiplex ------------------------------------------------
MUX=$(curl -sf -b "$JAR" -X POST -H 'Content-Type: application/json' \
  -d '{
        "name": "Mux A",
        "device": 0,
        "frequency": 474000000,
        "qam": 256,
        "symbol_rate": 6900,
        "network_id": 1,
        "ts_id": 1,
        "network_name": "Seaview Court",
        "active": true
      }' \
  "$BASE/api/dvb/muxes" | sed -n 's/.*"id":\([0-9]*\).*/\1/p')

# 4. assign the channels, in line-up order -------------------------------
#    this order fixes the service IDs; changing it later means a re-tune
LIST=$(IFS=,; echo "${IDS[*]}")

curl -sf -b "$JAR" -X POST -H 'Content-Type: application/json' \
     -d "{\"channel_ids\": [$LIST]}" \
     "$BASE/api/dvb/muxes/$MUX/channels"

rm -f "$JAR"

Zwei Details in diesem Skript sind kein Zufall. Das sleep 3 zwischen den Anlagevorgängen entspricht startup_stagger_seconds: Drei gleichzeitig geöffnete HLS-Ursprungsserver sind genau die Situation, die die Staffelung verhindern soll, und ein Einrichtungsskript ist der einfachste Weg, sie herbeizuführen. Außerdem werden die Sender in einem Aufruf statt in dreien zugewiesen, weil die Reihenfolge der Zuweisung die Service-IDs festlegt — die Liste zuerst aufzubauen und einmal zu senden bedeutet, dass die Senderliste gleich beim ersten Versuch wie beabsichtigt nummeriert ist.

Hinweise und Einschränkungen

• Fehler sind JSON. Eine fehlgeschlagene Anfrage liefert einen passenden Statuscode und einen JSON-Body mit einer Beschreibung des Problems. Eine HTML-Antwort bedeutet, dass die Anfrage nicht authentifiziert war und auf die Login-Seite umgeleitet wurde — prüfen Sie die Cookie-Datei, bevor Sie den Body untersuchen.
• PUT /api/settings führt zusammen. Senden Sie nur die Einstellungen, die Sie ändern wollen; alles Ausgelassene behält seinen aktuellen Wert. Eine Änderung der Engine-Parameter, von udp_device, default_engine, enable_dummy_listeners, overwrite_srt_latency oder overwrite_pkt_size startet jeden aktiven Sender neu, weil diese Einstellungen bestimmen, wie jede Engine läuft. Andere Einstellungen greifen ohne Neustart.
• Rate-Limiting ist kein Ersatz für zwischengespeicherte Daten. /api/metrics wird etwa zwei Sekunden zwischengespeichert; ein Dashboard, das alle 250 ms pollt, erhält acht identische Antworten und keine zusätzliche Information.

Eine vollständige Lese-API, Export und Import der gesamten Konfiguration sowie API-Tokens anstelle von Session-Cookies sind alle geplant. Sie stehen mit allem Übrigen auf der Roadmap-Seite.