uptime-kuma-api

uptime-kuma-api is a Python wrapper around Uptime Kuma’s Socket.IO API, the same real-time interface the Uptime Kuma dashboard itself uses. It exposes a single UptimeKumaApi class whose methods mirror the dashboard’s actions - logging in, creating and editing monitors, wiring up notifications, managing status pages, tags, proxies, Docker hosts, and maintenance windows - as ordinary synchronous Python calls, hiding the underlying event emit/listen cycle entirely.

The library was built to let Uptime Kuma be configured declaratively, most notably as the engine behind the ansible-uptime-kuma Ansible collection from the same author. Raw dashboard payloads are parsed into typed enums (MonitorType, MonitorStatus, AuthMethod, DockerType) so callers get structured, comparable values instead of opaque dashboard integers and strings.

What You Get

• A synchronous UptimeKumaApi client that connects, authenticates (including 2FA), and issues dashboard actions as regular method calls
• Full CRUD coverage for monitors, notifications, proxies, status pages, tags, Docker hosts, and maintenance windows
• Automatic parsing of raw Socket.IO payloads into typed enums (MonitorType, MonitorStatus, AuthMethod, DockerType) instead of raw dashboard integers
• Context-manager support (with UptimeKumaApi(...) as api:) that disconnects the socket automatically when a block exits
• Read access to heartbeats, uptime stats, average ping, certificate info, and database size/maintenance operations

Common Use Cases

• Provisioning and syncing Uptime Kuma monitors from infrastructure-as-code pipelines instead of clicking through the dashboard
• Backing the ansible-uptime-kuma collection to let Ansible playbooks declare monitor and notification state
• Bulk-importing or migrating monitor configurations between Uptime Kuma instances
• Scripting periodic exports of heartbeat/uptime data for external reporting or backup

Under The Hood

Architecture The package centers on a single UptimeKumaApi class in api.py that wraps a python-socketio client. Every public method (add_monitor, get_notifications, login, and so on) follows the same pattern: emit a Socket.IO event through an internal _call() helper, then block on wait_for_event() until the dashboard’s corresponding state event arrives, so an inherently asynchronous, event-driven protocol is presented as a synchronous request/response API. Domain concerns are split into small companion modules - monitor_type.py, monitor_status.py, auth_method.py, docker_type.py, event.py, incident_style.py, maintenance_strategy.py, and proxy_protocol.py for enums, plus notification_providers.py for per-provider field metadata and docstrings.py for dynamically composed docstrings. The design is flat rather than layered, organized by dashboard resource (monitors, notifications, proxies, status pages, tags, Docker hosts, maintenance) instead of by abstraction level, so it stays tightly coupled to Uptime Kuma’s internal Socket.IO event names and would need updating whenever those change.

Tech Stack Built for Python 3.7+ with python-socketio[client] as the transport for the Socket.IO connection, requests for any plain HTTP calls, and packaging for comparing Uptime Kuma version strings against supported ranges. Packaging is handled with a classic setup.py (no pyproject.toml/PEP 517 metadata), documentation is built with Sphinx and published to Read the Docs via .readthedocs.yaml, and there is no containerization or deployment tooling since this is a library consumed by other applications, notably the ansible-uptime-kuma collection.

Code Quality The repository ships an extensive tests/ suite (18 files) built on Python’s standard unittest, exercised through run_tests.sh against a real running Uptime Kuma instance rather than mocks, giving genuine integration coverage of monitors, notifications, 2FA, Docker hosts, and maintenance windows. There is no CI workflow configuration in the repository, so this test suite does not appear to run automatically on every change. Method signatures carry type hints (e.g. -> list[dict], -> dict), naming is consistent snake_case throughout, and there is no linter or formatter configuration present.

API Design The library’s main value is ergonomic: it collapses python-socketio’s event-driven connect/emit/listen dance into direct, discoverable method calls that mirror the dashboard’s own actions, and it auto-converts raw dashboard payloads into typed enums instead of leaving callers to interpret integers and strings. Context-manager support (with UptimeKumaApi(...) as api:) removes the need to remember to disconnect. Parameter documentation is composed centrally in docstrings.py and appended to methods that share the same option sets (monitor, proxy, notification, tag), reducing duplication across the ~60-plus public methods, though the underlying API surface is inherently large simply because it mirrors everything the dashboard can do.