Uptime Kuma API — kompletny przewodnik (REST + Socket.IO)

Dlaczego automatyzacja monitoringu ma znaczenie

Ręczne zarządzanie monitorami jest akceptowalne dla kilku stron — ale gdy monitorujesz dziesiątki lub setki usług, automatyzacja staje się koniecznością. API Uptime Kuma pozwala na programistyczne tworzenie monitorów, zarządzanie powiadomieniami, integrację z CI/CD pipeline i automatyczne reagowanie na incydenty.

Typowe scenariusze automatyzacji:

• Infrastructure as Code — definiowanie monitorów w YAML/JSON i wdrażanie ich automatycznie (Terraform, Ansible, skrypty)
• CI/CD pipeline — automatyczne tworzenie monitora po deployu nowej usługi
• Auto-scaling — dodawanie/usuwanie monitorów gdy infrastruktura się skaluje
• Custom dashboardy — pobieranie danych monitoringu do własnych narzędzi
• Prometheus + Grafana — profesjonalne wizualizacje metryk
• Integracja z ITSM — automatyczne tworzenie ticketów w Jira/ServiceNow

Dwa interfejsy API — REST i Socket.IO

Uptime Kuma oferuje dwa interfejsy programistyczne, każdy z innym przeznaczeniem:

Autentykacja — API Key i tokeny

Od Uptime Kuma 2.x dostępne są API Keys generowane w Settings → API Keys. Token dodajesz jako header:

Authorization: Bearer kuma_xxxxxxxxxxxxxxxxxx

Dla Socket.IO możesz też użyć klasycznego loginu username/password. Biblioteka Python uptime-kuma-api obsługuje oba sposoby, włącznie z 2FA (TOTP).

REST API — Push URL i Prometheus metrics

Push URL (Heartbeat)

Każdy Push Monitor generuje unikalny URL. Twój skrypt wysyła GET na ten URL po zakończeniu zadania:

# Heartbeat po zakończeniu backupu
curl -s "https://uptime.twoja-domena.pl/api/push/abc123?status=up&msg=Backup+OK&ping=42"

# W skrypcie bash
backup_start=$(date +%s)
rsync -av /data /backup/
backup_time=$(( $(date +%s) - backup_start ))
curl -s "https://uptime.twoja-domena.pl/api/push/abc123?status=up&msg=Backup+done&ping=$backup_time"

Prometheus /metrics

Endpoint /metrics wystawia metryki w formacie Prometheus:

curl -s https://uptime.twoja-domena.pl/metrics

# Przykład odpowiedzi:
monitor_status{monitor_name="Strona WWW",monitor_type="http"} 1
monitor_response_time{monitor_name="Strona WWW",monitor_type="http"} 245
monitor_cert_days_remaining{monitor_name="Strona WWW"} 67

Dodaj ten endpoint do konfiguracji Prometheus (scrape_configs) i twórz dashboardy w Grafana z historią uptime, wykresami czasu odpowiedzi i alertami.

Socket.IO API — real-time CRUD

Socket.IO API to główny interfejs programistyczny Uptime Kuma. Oferuje pełny CRUD w czasie rzeczywistym — tworzenie, odczyt, aktualizację i usuwanie wszystkich zasobów.

Dostępne operacje

• Monitory: add, edit, delete, pause, resume, getMonitorList, getMonitor
• Powiadomienia: addNotification, editNotification, deleteNotification, testNotification
• Status Pages: addStatusPage, editStatusPage, deleteStatusPage, postIncident, unpinIncident
• Tagi: addTag, editTag, deleteTag, addMonitorTag, deleteMonitorTag
• Maintenance: addMaintenance, editMaintenance, deleteMaintenance
• Docker Hosts: addDockerHost, editDockerHost, deleteDockerHost, testDockerHost
• Proxy: addProxy, editProxy, deleteProxy
• 2FA: prepare2FA, save2FA, disable2FA

Przykład Python — tworzenie monitora

from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.twoja-domena.pl")
api.login("admin", "password123")

# Utwórz monitor HTTP
result = api.add_monitor(
    type="http",
    name="API Production",
    url="https://api.mojafirma.pl/health",
    interval=30,
    maxretries=3,
    accepted_statuscodes=["200-299"],
    notificationIDList=[1, 2]  # Telegram + Email
)
print(f"Monitor ID: {result['monitorID']}")

api.disconnect()

Zarządzanie monitorami przez API

Masowe tworzenie monitorów z pliku YAML

# monitors.yaml
monitors:
  - name: "Strona WWW"
    type: http
    url: "https://www.mojafirma.pl"
    interval: 30
  - name: "API v2"
    type: http
    url: "https://api.mojafirma.pl/v2/health"
    interval: 20
  - name: "Baza MySQL"
    type: mysql
    hostname: "db.mojafirma.pl"
    port: 3306
    interval: 60

import yaml
from uptime_kuma_api import UptimeKumaApi

api = UptimeKumaApi("https://uptime.twoja-domena.pl")
api.login("admin", "password123")

with open("monitors.yaml") as f:
    config = yaml.safe_load(f)

for m in config["monitors"]:
    result = api.add_monitor(**m)
    print(f"Created: {m['name']} (ID: {result['monitorID']})")

api.disconnect()

Przykłady automatyzacji — skrypty i integracje

CI/CD — monitor po deployu

# GitHub Actions - dodaj monitor po deployu
- name: Create Uptime Kuma monitor
  run: |
    pip install uptime-kuma-api
    python3 -c "
    from uptime_kuma_api import UptimeKumaApi
    api = UptimeKumaApi('${{ secrets.KUMA_URL }}')
    api.login_by_token('${{ secrets.KUMA_TOKEN }}')
    api.add_monitor(type='http', name='PR-${{ github.event.number }}',
                    url='https://pr-${{ github.event.number }}.preview.mojafirma.pl',
                    interval=60)
    api.disconnect()
    "

Heartbeat dla cronjobów

#!/bin/bash
# /etc/cron.daily/backup-with-heartbeat.sh
PUSH_URL="https://uptime.twoja-domena.pl/api/push/backup-daily"

# Wykonaj backup
if borgmatic --config /etc/borgmatic.d/config.yaml; then
    curl -s "${PUSH_URL}?status=up&msg=Backup+OK"
else
    curl -s "${PUSH_URL}?status=down&msg=Backup+FAILED"
fi

Narzędzia społeczności

Podsumowanie

API Uptime Kuma to potężne narzędzie automatyzacji monitoringu. Dwa interfejsy — REST (Push URL, Prometheus) i Socket.IO (pełny CRUD) — pokrywają wszystkie scenariusze, od prostego heartbeat po Infrastructure as Code z Terraform.

Kluczowe elementy API:

• Push URL — REST endpoint dla heartbeat (cronjobowy, backupy)
• Prometheus /metrics — integracja z Grafana
• Socket.IO — pełny CRUD w czasie rzeczywistym
• uptime-kuma-api (Python) — wygodny wrapper z context manager
• AutoKuma / Terraform / Ansible — Infrastructure as Code

Najczęściej zadawane pytania