API do Uptime Kuma: o que existe e o que usar no lugar

Em resumo

O Uptime Kuma não deixa você criar um monitor via HTTP. Toda a superfície HTTP dele se resume a badges de status, dados públicos das páginas de status, um endpoint push e um scrape do Prometheus. O painel controla todo o resto via Socket.IO, uma interface privada que o projeto nunca prometeu manter estável. Toda biblioteca anunciada como API do Uptime Kuma é um cliente dessa interface.

Você quer cinquenta monitores criados a partir de um CSV. Ou uma verificação adicionada no mesmo pull request que adiciona o serviço. Ou um script de deploy que pausa um monitor enquanto roda e depois o reativa. Então você vai procurar a documentação da API e não encontra.

Ela não existe. Por isso, aqui está a superfície tal como está na versão 2.5.3, lida direto do código-fonte em 5 de setembro de 2026.

Todas as rotas HTTP que o Uptime Kuma serve

Dois routers do Express carregam quase tudo, mais algumas rotas registradas direto no app. Tudo o que não está nesta tabela serve o próprio app de página única, incluindo o HTML da página de status em /status/:slug, ou então são imagens enviadas, o robots.txt, um link well-known para troca de senha e a página de configuração do banco de dados da primeira execução.

Leia a coluna de autenticação de novo. Uma única rota grava alguma coisa, e o que ela grava é um único heartbeat. Nada aqui cria um monitor, e nada aqui sequer lista os seus monitores, a não ser que você já os tenha publicado numa página de status pública.

O site ou a API que você quer monitorar > monitorar

A chave de API faz menos do que o nome sugere

O Uptime Kuma tem um recurso de chaves de API, nas configurações, com data de validade e um botão para ativar e desativar. É fácil supor que essa é a credencial REST que faltava.

A chave funciona em exatamente uma rota, o scrape do Prometheus em /metrics. No código-fonte, o apiAuth é aplicado ali e em nenhum outro lugar, então a chave não consegue tocar em monitor nenhum.

Duas coisas a saber antes de construir em cima disso. Se as chaves de API estiverem desativadas, esse mesmo endpoint volta a usar HTTP Basic com o seu nome de usuário e a sua senha de admin, então uma configuração de scrape carrega ou uma chave ou o login da instância inteira. E o caminho da chave tem limite de 60 requisições por minuto para a instância toda, com o caminho de login limitado a 20.

A interface real é o Socket.IO

Tudo o que a interface web faz, ela faz emitindo eventos Socket.IO para o servidor. Os eventos de monitor são o que você esperaria de uma API REST, no formato errado:

add             editMonitor      deleteMonitor
pauseMonitor    resumeMonitor    getMonitorList
getMonitor      getMonitorBeats  getTags

Criar um monitor é um evento chamado, literalmente, add.

Para chegar a qualquer um deles, você primeiro faz login, como admin, por esse mesmo socket. O evento de login devolve um JWT que você pode reutilizar e, se a conta tiver a autenticação de dois fatores ativada, o seu script também precisa gerar um código TOTP a partir do segredo compartilhado. Depois você emite add com um objeto de monitor cujo formato não está escrito em lugar nenhum, então ou você copia o que o navegador envia, ou se apoia no wrapper de alguém que já fez isso.

Isso importa por três motivos. A credencial é a instância inteira: não há token somente leitura nem escopo por monitor, então um script de deploy que pausa um monitor está segurando o login que poderia apagar todos eles e trocar a senha de admin. O formato do payload não é um contrato, é o que quer que a interface atual envie, então um campo pode ser renomeado numa versão menor sem que o projeto tenha quebrado nada, porque nada fora da interface deveria depender dele. E nada disso é documentado, então você aprende lendo o server/server.js ou lendo o wrapper de outra pessoa.

Isso é de propósito, e o projeto diz isso

Vale ser justo com o Uptime Kuma aqui. Isso não é descaso. O README lista as motivações do projeto, e uma delas é:

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

O Uptime Kuma se propôs a ser um app de página única com um socket ativo por trás, o que combina bem com um painel que você deixa aberto o dia inteiro. Uma API REST nunca foi o objetivo, então pedir uma é pedir um produto diferente.

O pedido também não está sendo ignorado. A issue 118, “API functionality”, está aberta desde julho de 2021, com 776 reações e 77 comentários, o que faz dela a issue aberta com mais reações do repositório. O mantenedor foi além de reconhecê-la. Em outubro de 2023, ele abriu um pull request ligado a essa issue, o número 3854, chamado “Document the Socket.io API and try to convert it to a HTTP request”. Ele ainda é um rascunho, e tanto ele quanto a issue estavam abertos quando este texto foi escrito.

O ecossistema de wrappers, com datas

Toda biblioteca chamada de API do Uptime Kuma é um cliente Socket.IO com uma roupa mais bonita. As contagens de estrelas e as datas de commit abaixo vêm da API do GitHub em 5 de setembro de 2026, e não das páginas dos projetos, porque um repositório pode parecer vivo por causa de um branch do dependabot enquanto ninguém mexe no código há dois anos.

Ou seja, o cliente para o qual quase todo mundo aponta é anterior ao Uptime Kuma 2 por completo, e os forks que cobrem a versão 2 são minúsculos. Dois deles são a mesma ideia, começada com um ano de diferença por pessoas diferentes, com onze estrelas cada. É isso que acontece quando o protocolo por baixo não é estável nem documentado: as pessoas reconstroem o mesmo wrapper em vez de manter um juntas.

O que você pode fazer hoje

Se você vai continuar no Uptime Kuma, aqui estão as opções, mais ou menos em ordem de quanto sono cada uma vai custar a você.

Os monitores push são a única superfície de automação que o projeto suporta deliberadamente. O seu job chama uma URL com token quando termina, e o endpoint aceita status=up ou status=down, mais os parâmetros opcionais msg e ping. Isso cobre cron e trabalho em lote sem chegar perto do socket. É a mesma ideia das verificações de heartbeat para cron jobs, e o motivo por trás de por que cron jobs falham em silêncio.

Para ler o estado, faça o scrape de /metrics com uma chave de API e consulte os dados por lá. Esse é o caminho de leitura suportado, e ele é estável. Se os dados já são públicos de qualquer forma, /api/status-page/heartbeat/:slug devolve heartbeats reais sem credencial nenhuma, limitado aos monitores que você escolheu publicar.

Um wrapper de socket serve para trabalho que você está acompanhando, como uma importação única de cinquenta monitores que você roda uma vez e confere à mão. Fixe a versão do wrapper, fixe a versão do seu Kuma e mantenha isso fora de qualquer pipeline que ninguém esteja olhando.

Escrever direto no banco de dados é o caminho a evitar. As pessoas fazem isso mesmo assim. O Kuma guarda estado em memória e grava heartbeats continuamente, então uma escrita pelas costas dele é uma instância corrompida esperando o próximo restart.

Se você precisa de monitoramento como código

Este é o ponto em que a ferramenta e o trabalho deixam de combinar. Se os seus monitores precisam morar no Git, passar por revisão num pull request e ser criados por uma conta de serviço que não consegue também apagá-los, você está pedindo a uma ferramenta feita em torno do painel que se comporte como uma feita em torno da API.

Foi em torno dessa lacuna que construímos o Uptimepage. Os monitores são definidos num provider do Terraform ou criados por uma API REST documentada com tokens com escopo, então um job de CI consegue adicionar uma verificação sem ter nas mãos as chaves da conta. Também há um servidor MCP, se quem cria os monitores é um agente e não um pipeline. A comparação lado a lado é a versão curta.

O Kuma continua sendo a resposta certa para muitos homelabs e equipes pequenas, e a nossa seleção de monitores de uptime auto-hospedados diz isso. Este é um limite específico, e é o que a maioria das pessoas encontra em segundo lugar, logo depois do único login compartilhado.

Perguntas frequentes

O Uptime Kuma tem uma API REST?

O Uptime Kuma não tem API REST para gerenciar monitores. As rotas HTTP que ele expõe são badges somente leitura, o JSON da página de status pública, o endpoint push dos monitores de heartbeat e um endpoint de métricas do Prometheus. Criar, editar, pausar e apagar monitores acontece via Socket.IO.

Como crio um monitor no Uptime Kuma a partir de um script?

Você abre uma conexão Socket.IO, faz login com o nome de usuário e a senha de admin e emite o evento add com um objeto de monitor. Não há schema documentado para esse objeto, então na prática você copia o que a interface web envia, ou usa um wrapper da comunidade que já fez isso.

O que uma chave de API do Uptime Kuma consegue fazer?

Uma chave de API autentica exatamente um endpoint, o das métricas do Prometheus em /metrics. Ela não consegue criar, editar, pausar nem apagar um monitor, e não é um token de acesso geral para o resto do app.

A biblioteca Python uptime-kuma-api ainda é mantida?

O wrapper Python original não recebe nenhum commit desde setembro de 2023, e a própria tabela de compatibilidade dele para no Uptime Kuma 1.23.2. A versão 2 é a linha atual, então o ecossistema se dividiu em vários forks pequenos em vez de um pacote mantido.

Qual é o jeito mais seguro de automatizar o Uptime Kuma hoje?

Os monitores push são a única superfície de automação que o Uptime Kuma suporta de propósito. O seu job chama uma URL com token quando termina, o que cobre cron e trabalho em lote sem passar pela interface Socket.IO privada.