API de Uptime Kuma: qué existe y qué usar en su lugar

En resumen

Uptime Kuma no le deja crear un monitor por HTTP. Toda su superficie HTTP se reduce a insignias de estado, datos públicos de páginas de estado, un endpoint push y un scrape de Prometheus. El panel maneja todo lo demás por Socket.IO, una interfaz privada que el proyecto nunca prometió mantener estable. Cada biblioteca que se presenta como API de Uptime Kuma es un cliente de esa interfaz.

Quiere crear cincuenta monitores a partir de un CSV. O añadir una comprobación en el mismo pull request que añade el servicio. O un script de despliegue que pause un monitor mientras se ejecuta y luego lo reactive. Así que busca la documentación de la API y no la encuentra.

No existe. Así que esta es la superficie tal como está en la versión 2.5.3, leída del código fuente el 5 de septiembre de 2026.

Todas las rutas HTTP que sirve Uptime Kuma

Dos routers de Express llevan casi todo, más unas pocas rutas registradas directamente en la aplicación. Todo lo que no está en esta tabla sirve la propia aplicación de una sola página, incluido el HTML de la página de estado en /status/:slug, o bien son imágenes subidas, robots.txt, un enlace well-known para cambiar la contraseña y la página de configuración de la base de datos del primer arranque.

Vuelva a leer la columna de autenticación. Una sola ruta escribe algo, y lo que escribe es un único heartbeat. Nada de aquí crea un monitor, y nada de aquí llega siquiera a listar sus monitores, salvo que ya los haya publicado en una página de estado pública.

El sitio o la API que quiere vigilar > monitorear

La clave de API hace menos de lo que sugiere su nombre

Uptime Kuma tiene una función de claves de API, en los ajustes, con fechas de caducidad y un interruptor para activarlas. Es fácil suponer que esa es la credencial REST que faltaba.

La clave funciona exactamente en una ruta, el scrape de Prometheus en /metrics. En el código fuente, apiAuth se aplica ahí y en ningún otro lugar, así que la clave no puede tocar un monitor en absoluto.

Dos cosas que conviene saber antes de construir sobre ella. Si las claves de API están desactivadas, ese mismo endpoint recurre a HTTP Basic con su nombre de usuario y su contraseña de administrador, así que una configuración de scrape lleva o bien una clave o bien el inicio de sesión de toda la instancia. Y la ruta de la clave tiene un límite de 60 solicitudes por minuto para toda la instancia, y la del inicio de sesión, de 20.

La interfaz real es Socket.IO

Todo lo que hace la interfaz web lo hace emitiendo eventos Socket.IO hacia el servidor. Los eventos de monitores son lo que querría de una API REST, pero con la forma equivocada:

add             editMonitor      deleteMonitor
pauseMonitor    resumeMonitor    getMonitorList
getMonitor      getMonitorBeats  getTags

Crear un monitor es un evento que se llama, literalmente, add.

Para llegar a cualquiera de ellos, primero inicia sesión como administrador por ese mismo socket. El evento de inicio de sesión devuelve un JWT que puede reutilizar, y si la cuenta tiene activada la autenticación de dos factores, su script también tiene que generar un código TOTP a partir del secreto compartido. Después emite add con un objeto de monitor cuya forma no está escrita en ninguna parte, así que o copia lo que envía el navegador o se apoya en el wrapper de alguien que ya lo hizo.

Eso importa por tres razones. La credencial es toda la instancia: no hay token de solo lectura ni alcance por monitor, así que un script de despliegue que pausa un monitor tiene en sus manos el inicio de sesión que podría borrarlos todos y cambiar la contraseña de administrador. La forma de la carga útil no es un contrato, es lo que la interfaz actual envíe en ese momento, así que un campo puede cambiar de nombre en una versión menor sin que el proyecto haya roto nada, porque nada fuera de la interfaz debía depender de él. Y nada de esto está documentado, así que se aprende leyendo server/server.js o leyendo el wrapper de otra persona.

Es a propósito, y el proyecto lo dice

Aquí conviene ser justos con Uptime Kuma. Esto no es dejadez. El README enumera las motivaciones del proyecto, y una de ellas, en el original, es:

Try to use WebSocket with SPA instead of a REST API.

Uptime Kuma se propuso ser una aplicación de una sola página con un socket en vivo detrás, algo que encaja bien con un panel que se tiene abierto todo el día. Una API REST nunca fue el objetivo, así que pedir una es pedir otro producto.

Tampoco se está ignorando la petición. El issue 118, «API functionality», lleva abierto desde julio de 2021 con 776 reacciones y 77 comentarios, lo que lo convierte en el issue abierto con más reacciones del repositorio. El mantenedor fue más allá de reconocerlo. En octubre de 2023 abrió un pull request vinculado a ese issue, el número 3854, titulado «Document the Socket.io API and try to convert it to a HTTP request». Sigue siendo un borrador, y tanto él como el issue seguían abiertos cuando se escribió esto.

El ecosistema de wrappers, con fechas

Cada biblioteca que se llama API de Uptime Kuma es un cliente de Socket.IO con un envoltorio más bonito. Los recuentos de estrellas y las fechas de commit de abajo proceden de la API de GitHub el 5 de septiembre de 2026, no de las páginas de los proyectos, porque un repositorio puede parecer vivo gracias a una rama de dependabot mientras nadie ha tocado el código en dos años.

Así que el cliente al que enlaza casi todo el mundo es anterior por completo a Uptime Kuma 2, y los forks que sí cubren la versión 2 son diminutos. Dos de ellos son la misma idea, empezada con un año de diferencia por personas distintas, con once estrellas cada uno. Eso es lo que pasa cuando el protocolo de debajo no es estable ni está escrito en ninguna parte: la gente reconstruye el mismo wrapper en lugar de mantener uno entre todos.

Qué puede hacer hoy

Si se queda con Uptime Kuma, esto es lo que puede hacer, más o menos en orden de cuánto sueño le va a quitar.

Los monitores push son la única superficie de automatización que el proyecto admite deliberadamente. Su tarea llama a una URL con token cuando termina, y el endpoint acepta status=up o status=down más los parámetros opcionales msg y ping. Eso cubre las tareas cron y por lotes sin acercarse al socket. Es la misma idea que las comprobaciones heartbeat para tareas cron, y la razón detrás de por qué las tareas cron fallan en silencio.

Para leer el estado, haga scrape de /metrics con una clave de API y consulte los datos ahí. Esa es la vía de lectura admitida, y es estable. Si los datos son públicos de todos modos, /api/status-page/heartbeat/:slug devuelve heartbeats reales sin credenciales, limitados a los monitores que eligió publicar.

Un wrapper del socket sirve para trabajo que usted está vigilando, como una importación puntual de cincuenta monitores que ejecuta una vez y revisa a mano. Fije la versión del wrapper, fije su versión de Kuma y manténgalo fuera de cualquier pipeline que nadie esté mirando.

Escribir directamente en la base de datos es lo que hay que evitar. La gente lo hace igualmente. Kuma mantiene el estado en memoria y escribe heartbeats continuamente, así que una escritura a sus espaldas es una instancia corrupta esperando al siguiente reinicio.

Si necesita monitoreo como código

Este es el punto en que la herramienta y el trabajo dejan de encajar. Si sus monitores tienen que vivir en Git, revisarse en un pull request y crearse con una cuenta de servicio que no pueda también borrarlos, le está pidiendo a una herramienta pensada primero como panel que se comporte como una pensada primero como API.

En torno a ese hueco construimos Uptimepage. Los monitores se definen con un proveedor de Terraform o se crean mediante una API REST documentada con tokens de alcance limitado, así que una tarea de CI puede añadir una comprobación sin tener las llaves de la cuenta. También hay un servidor MCP, si lo que crea los monitores es un agente y no un pipeline. La comparativa lado a lado es la versión corta.

Kuma sigue siendo la respuesta correcta para muchos homelabs y equipos pequeños, y nuestro repaso de monitores de disponibilidad autoalojados lo dice. Este es un límite concreto, y es el segundo con el que choca la mayoría, justo después del único inicio de sesión compartido.

Preguntas frecuentes

¿Tiene Uptime Kuma una API REST?

Uptime Kuma no tiene una API REST para gestionar monitores. Las rutas HTTP que sí expone son insignias de solo lectura, el JSON público de la página de estado, el endpoint push para los monitores de heartbeat y un endpoint de métricas de Prometheus. Crear, editar, pausar y eliminar monitores se hace, en cambio, por Socket.IO.

¿Cómo creo un monitor en Uptime Kuma desde un script?

Abra una conexión Socket.IO, inicie sesión con el nombre de usuario y la contraseña de administrador y emita el evento add con un objeto de monitor. No hay ningún esquema documentado para ese objeto, así que en la práctica se copia lo que envía la interfaz web, o se usa un wrapper de la comunidad que ya lo hizo.

¿Qué puede hacer una clave de API de Uptime Kuma?

Una clave de API autentica exactamente un endpoint, las métricas de Prometheus en /metrics. No puede crear, editar, pausar ni eliminar un monitor, y no es un token de acceso general para el resto de la aplicación.

¿Se sigue manteniendo la biblioteca de Python uptime-kuma-api?

El wrapper original de Python no tiene ningún commit desde septiembre de 2023, y su propia tabla de compatibilidad se detiene en Uptime Kuma 1.23.2. La versión 2 es la línea actual, así que el ecosistema se ha dividido en varios forks pequeños en lugar de un único paquete mantenido.

¿Cuál es la forma más segura de automatizar Uptime Kuma hoy?

Los monitores push son la única superficie de automatización que Uptime Kuma admite a propósito. Su tarea llama a una URL con token cuando termina, lo que cubre las tareas cron y por lotes sin tocar en absoluto la interfaz privada de Socket.IO.