API HTTP

Convenciones

Los cuerpos de petición y respuesta son JSON. Los endpoints que reciben un cuerpo esperan Content-Type: application/json. En toda esta página, la URL base es http://headend.local:8080; sustitúyala por la dirección y el puerto que haya configurado con --port.

Los identificadores de canal en las rutas son el id numérico del archivo de configuración. Se reutilizan tras una eliminación, así que un script que guarde un identificador a lo largo de una reconfiguración puede actuar sobre el canal equivocado.

Autenticación

Método	Ruta	Finalidad
GET	/login	La propia página de inicio de sesión. No le sirve de nada a un script; se incluye para que una respuesta HTML inesperada a una llamada a la API se reconozca como una redirección a ella.
POST	/api/login	Intercambia usuario y contraseña por una cookie de sesión. Las credenciales son los valores de CASTMUX_WEB_USERNAME y CASTMUX_WEB_PASSWORD.
POST	/api/logout	Invalida la sesión actual.

Con curl, guarde la cookie en un archivo (cookie jar) al iniciar sesión y preséntelo después:

# 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

Sesiones, no tokens

Actualmente no hay tokens de API. Una integración de larga duración debe iniciar sesión, conservar la cookie y volver a iniciar sesión cuando caduque. La autenticación por token está prevista.

Endpoints públicos

Método	Ruta	Finalidad
GET	/api/version	Versión, commit y fecha de compilación del binario en ejecución. Sin autenticación de forma deliberada, para que un sistema de monitorización pueda confirmar qué hay desplegado en cada equipo de un parque sin recibir credenciales con las que cambiar nada en ellos.

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

Solo loopback

Método	Ruta	Finalidad
POST	/api/internal/streams/{id}/restart	Reinicia un canal, para un supervisor que se ejecuta en el propio equipo. El parámetro opcional ?reason= se escribe en el registro, de modo que un reinicio indica allí por qué se produjo. Devuelve el nombre del canal y si se ha reiniciado un motor en ejecución. El watchdog suministrado lo usa para recuperar un canal atascado sin reiniciar todo el contenedor y dejar con él fuera del aire a todos los canales sanos.

Este endpoint no requiere inicio de sesión. En su lugar, rechaza cualquier conexión que no proceda de una dirección loopback (127.0.0.1 o ::1), con 403 y una línea de registro que identifica al llamante. Así se evita que la contraseña de administrador tenga que estar en un archivo en disco para que la lea el watchdog. Para llegar al endpoint ya hace falta una shell en el equipo.

No ponga un proxy delante del puerto web en el mismo host

Castmux se ejecuta con red de host, así que la comprobación de loopback ve lo que se conecte a él en el propio equipo. Un proxy inverso en el equipo que reenvíe a 127.0.0.1:8080 haría que todas las peticiones que retransmite parecieran locales. Cualquiera que pudiera llegar al proxy podría entonces reiniciar canales sin iniciar sesión. Ponga el proxy en otra máquina, o haga que bloquee /api/internal/.

Canales

Método	Ruta	Finalidad
Ciclo de vida
POST	/api/channels	Crea un canal. El cuerpo tiene la misma estructura que una entrada de streams en el archivo de configuración. Se devuelve el identificador asignado.
PUT	/api/channels/{id}	Sustituye los ajustes de un canal existente. Un canal en ejecución se reinicia si el cambio afecta a su funcionamiento.
DELETE	/api/channels/{id}	Elimina un canal. Primero lo detiene. El identificador queda disponible para reutilizarse.
POST	/api/channels/{id}/restart	Reinicia un canal sin tocar los demás. Es lo primero que hay que probar cuando un solo canal se comporta mal y el resto están sanos.
Estado
POST	/api/streams/{id}/active	Habilita o deshabilita un canal. Un canal deshabilitado conserva su configuración, pero nunca se inicia.
POST	/api/streams/{id}/force-always-on	Activa o desactiva el forzado always-on. Activado, el canal funciona de forma continua; desactivado, funciona cuando la detección de espectadores ve que alguien lo está viendo.
Inspección
GET	/api/channels	Una lista breve de todos los canales: id, name, address y port de destino, y epg_id. Basta para descubrir qué canales existen. No devuelve todos los ajustes de un canal —fuente, motor, perfil, supervisión—, así que un script que los necesite debe leer el archivo de configuración.
GET	/api/channels/{id}/ts-quality	Calidad del transport stream de un canal: la última muestra, los totales acumulados de errores de continuidad, de transporte y de PCR, y el historial de los últimos 30 minutos en intervalos de 5 segundos. También indica si la monitorización está en marcha para el canal y cómo se mide su temporización PCR. Consulte Calidad del transport stream.
GET	/api/channels/{id}/logs	Salida reciente del motor de un canal. Aquí es donde aparece un error de la fuente con las palabras que usó realmente el servidor de origen, en lugar de como un fallo genérico.
GET	/api/channels/resolutions	La resolución seleccionada actualmente para cada canal, y si coincide exactamente con el perfil solicitado o es el escalón más cercano que ofrecía el servidor de origen. Se sirve desde la caché; no se bloquea esperando descargas del servidor de origen.
Vista previa
POST	/api/channels/{id}/preview	Inicia una vista previa de un canal visible en el navegador.
POST	/api/channels/{id}/preview/stop	La detiene. Las vistas previas consumen CPU real, así que deténgalas explícitamente en lugar de confiar en que se cierre la página.

# 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

Guía de programación

Método	Ruta	Finalidad
Fuentes
POST	/api/epg/sources	Añade una fuente XMLTV. Cuerpo: {"name": "...", "url": "..."}. Devuelve el id de la nueva fuente. La lista de canales de la fuente se descarga en segundo plano.
PUT	/api/epg/sources/{id}	Cambia el nombre de una fuente o la dirige a una nueva URL, con el mismo cuerpo. Los datos almacenados se conservan y se sustituyen en la siguiente sincronización.
DELETE	/api/epg/sources/{id}	Elimina una fuente y sus datos de guía almacenados. Los canales asociados a ella conservan su epg_id.
POST	/api/epg/sources/{id}/sync	Descarga la fuente en ese momento y almacena los programas de los canales asociados. Es síncrono: la respuesta indica el resultado real y, con una guía grande, puede tardar minutos.
Asociación y datos
GET	/api/epg/channels	Todas las fuentes, indexadas por su id, con su nombre, URL, última descarga y estado, y los identificadores de guía que ofrecen.
POST	/api/epg/map	Asocia un canal a un identificador de guía. Cuerpo: {"stream_id": 3, "tvg_id": "rtl.de"}. Un tvg_id vacío elimina la asociación. Se guarda en el epg_id del canal.
GET	/api/epg/now	Qué se emite ahora y qué viene a continuación, para todos los canales asociados en una sola llamada. Un canal asociado sin nada en emisión aparece con now vacío, lo que es distinto de un canal no asociado, que no aparece.

Licencia

Método	Ruta	Finalidad
GET	/api/licence	El estado de la licencia del equipo: state con un message y un detail legibles, can_stream, el device_code que le pedirá el soporte técnico y un contact de soporte. Si la última sincronización rechazó canales enviados por el servidor de licencias, también se incluyen los motivos. El token de licencia nunca se devuelve.
POST	/api/licence/retry	Realiza la comprobación con el servidor de licencias en ese momento en lugar de esperar al siguiente intento programado. Úselo después de corregir lo que bloqueaba la licencia, como una suscripción vencida o una regla del cortafuegos. Responde de inmediato; consulte /api/licence periódicamente para conocer el resultado.

Espectadores

Método	Ruta	Finalidad
GET	/api/viewers	Estado de espectadores de todos los canales en una sola llamada. Úselo para sondear en lugar de recorrer los canales uno a uno, lo que multiplica el número de peticiones por el tamaño de la parrilla.
GET	/api/streams/{id}/viewers	Detalle de un canal: la lista de direcciones de cliente unidas en ese momento, el recuento, un indicador de si hay un querier IGMP en el segmento y un indicador de si la detección está degradada.

Por qué existe un indicador “degraded”

Un recuento de cero espectadores tiene dos significados totalmente distintos: que nadie está viendo el canal, o que en este momento no podemos saberlo. Lo segundo ocurre cuando la captura de paquetes no puede iniciarse, la interfaz de captura desaparece, o no existe ningún querier y nadie ha hablado desde el último reinicio. Notificar ambos casos como 0 haría que una alerta de “sin espectadores” saltara por una avería de monitorización y, peor aún, haría indistinguible una ausencia real de espectadores de una cabecera ciega. Interprete degraded como “esta cifra no es una prueba”, y tenga en cuenta que con on_demand_fail_open activado los canales siguen emitiendo de todos modos.

Métricas y sistema

Método	Ruta	Finalidad
Medición
GET	/api/metrics	Métricas del sistema y por canal en un solo documento: CPU, memoria, tiempo de funcionamiento, estado y caudal de cada canal. Se guarda en caché durante unos dos segundos en el servidor, así que sondear más rápido devuelve las mismas cifras y solo le cuesta el procesamiento de las peticiones.
GET	/api/network-stats	Contadores a nivel de interfaz y resultados de accesibilidad de los hosts de ping_hosts.
GET	/api/udp-bitrate	Bitrate medido que realmente sale por el puerto de red, por canal. Es la señal de actividad independiente del motor: refleja lo que hay en el cable, no lo que un descodificador afirma estar produciendo.
Administración
PUT	/api/settings	Modifica los ajustes de global. Envíe solo las claves que quiera cambiar; lo que se omita conserva su valor actual. Solo PUT: no existe variante GET, así que lea los ajustes actuales del archivo de configuración.
GET	/api/network-interfaces	Todas las direcciones IPv4 del equipo, para elegir udp_device: dirección, interfaz, si la interfaz está activa, su subred y si la dirección se asignó por DHCP. Las direcciones loopback y link-local se omiten, porque ninguna de ellas es nunca la opción correcta. Las interfaces inactivas se muestran, no se ocultan, porque una interfaz inactiva es exactamente lo que necesita ver.
POST	/api/restart-all	Reinicia todos los canales. Los arranques se escalonan según startup_stagger_seconds, para que la parrilla completa no vuelva toda a la vez y falle en bloque.
POST	/api/restart-app	Reinicia la aplicación Castmux. Primero responde, luego se cierra de forma ordenada, y la política de reinicio del contenedor la vuelve a iniciar en pocos segundos. Todos los canales quedan brevemente fuera del aire. A diferencia de /api/reboot, no necesita nada en el host, así que funciona en cualquier despliegue en contenedor.
POST	/api/reboot	Reinicia el equipo. Todos los canales quedan fuera del aire mientras dura; no es un remedio para una avería de un canal.

Múltiplex DVB-C

Método	Ruta	Finalidad
Múltiplex
GET	/api/dvb/muxes	Enumera los múltiplex configurados con sus parámetros de RF y su estado actual. A diferencia de los canales, los múltiplex sí tienen un endpoint de lectura.
POST	/api/dvb/muxes	Crea un múltiplex.
PUT	/api/dvb/muxes/{id}	Actualiza los parámetros de RF o los identificadores de señalización. Cambiar la frecuencia, la modulación o la tasa de símbolos interrumpe la portadora.
DELETE	/api/dvb/muxes/{id}	Elimina un múltiplex. Los canales que transportaba no se eliminan.
POST	/api/dvb/muxes/{id}/active	Inicia o detiene la transmisión de la portadora.
Contenido y operaciones
POST	/api/dvb/muxes/{id}/channels	Asigna los canales transportados y su orden. El orden determina los identificadores de servicio, así que reordenar cambia la identificación de los servicios y puede obligar a los televisores a volver a sintonizar. Cuando pueda elegir, añada al final en lugar de insertar.
GET	/api/dvb/muxes/{id}/logs	Salida del multiplexor y del modulador para esta portadora.
POST	/api/dvb/muxes/{id}/hot-swap	Cambia el contenido de un múltiplex en funcionamiento sin interrumpir la portadora, para que los televisores sigan sintonizados en lugar de mostrar «sin señal» durante el cambio.
POST	/api/dvb/muxes/{id}/suspend	Suspende temporalmente el múltiplex, para realizar mantenimiento en el modulador o en la red de cable, sin eliminar la configuración.

Salida HDMI

Método	Ruta	Finalidad
POST	/api/hdmi/active	Habilita o deshabilita la salida HDMI.
POST	/api/hdmi/config	Establece qué canal se muestra en el puerto HDMI y cómo se reproduce.
GET	/api/hdmi/outputs	Lo que este equipo puede gestionar: vos (controladores de vídeo), drm_devices (dispositivos de pantalla) y audio_devices (cada uno con un value y una label, tal como los enumera el propio reproductor), además de la selección current. Los valores son exactamente los que acepta /api/hdmi/config.
GET	/api/hdmi/metrics	Estado y caudal de la salida HDMI.
GET	/api/hdmi/logs	Salida del proceso de reproducción HDMI.

Automatizar la configuración de una instalación

Un ejemplo práctico: iniciar sesión, crear tres canales, crear un múltiplex y asignarle los canales en el orden en que deben aparecer. Es toda la secuencia de puesta en marcha de una instalación pequeña, y merece la pena automatizarla porque introducir tres canales en un formulario es justo donde se originan las direcciones multicast transpuestas.

#!/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"

Dos detalles de ese script no son casuales. El sleep 3 entre creaciones coincide con startup_stagger_seconds: abrir tres servidores de origen HLS a la vez es exactamente la situación que el escalonado pretende evitar, y un script de configuración es la forma más fácil de recrearla. Además, los canales se asignan en una sola llamada y no en tres, porque el orden de asignación fija los identificadores de servicio: construir primero la lista y enviarla una vez hace que la parrilla quede numerada como se pretendía al primer intento.

Notas y limitaciones

• Los errores son JSON. Una petición fallida devuelve el código de estado correspondiente y un cuerpo JSON que describe el problema. Una respuesta HTML significa que la petición no estaba autenticada y se redirigió a la página de inicio de sesión; revise el cookie jar antes de depurar el cuerpo.
• PUT /api/settings fusiona. Envíe solo los ajustes que quiera cambiar; lo que se omita conserva su valor actual. Un cambio en los parámetros del motor, udp_device, default_engine, enable_dummy_listeners, overwrite_srt_latency u overwrite_pkt_size reinicia todos los canales activos, porque esos ajustes determinan cómo funciona cada motor. Los demás ajustes se aplican sin reinicio.
• Limitar la frecuencia no sustituye a los datos en caché. /api/metrics se guarda en caché durante unos dos segundos; un panel que lo sondee cada 250 ms obtiene ocho respuestas idénticas y ninguna información adicional.

Una API de lectura completa, la exportación e importación de toda la configuración y los tokens de API en lugar de cookies de sesión están previstos. Se enumeran con el resto en la página de la hoja de ruta.