Uptime Kuma API Wrapper

1.2.1 · active · verified Sat Apr 11

uptime-kuma-api is a Python wrapper for the Uptime Kuma WebSocket API, currently at version 1.2.1. It provides a programmatic interface for managing monitors and notifications in Uptime Kuma. This library is actively maintained with regular releases, often aligning with new Uptime Kuma versions, and requires Python 3.7 or newer. It was primarily developed to facilitate Uptime Kuma configuration via automation tools like Ansible.

Warnings

breaking Version 1.0.0 dropped support for Python 3.6. Users must upgrade to Python 3.7 or higher.
Fix: Upgrade your Python environment to 3.7+ before upgrading uptime-kuma-api to 1.0.0+.
breaking API version 1.0.0+ requires Uptime Kuma server version 1.21.3 or newer. Older Uptime Kuma instances (1.17.0 - 1.21.2) are only supported by uptime-kuma-api versions 0.x.
Fix: Ensure your Uptime Kuma server is updated to 1.21.3 or newer when using uptime-kuma-api 1.0.0+. Alternatively, stick to uptime-kuma-api versions <1.0.0 for older Uptime Kuma servers.
breaking With version 1.0.0, the `maintenance` parameter `timezone` was renamed to `timezoneOption`, the `wait_timeout` parameter was removed (use `timeout` instead), and the `get_heartbeat()` method was removed entirely.
Fix: Update method calls and parameter names: use `timezoneOption`, replace `wait_timeout` with `timeout`, and use `get_heartbeats()` or `get_important_heartbeats()` instead of the removed `get_heartbeat()`.
breaking From version 1.0.0, return values for methods like `get_heartbeats`, `avg_ping`, `uptime`, and `cert_info` have changed. Additionally, monitor and notification attribute types (e.g., `monitor['type']`, `monitor['status']`, `monitor['authMethod']`) now return `Enum` values (like `MonitorType.HTTP`) instead of raw strings or booleans.
Fix: Adjust code to expect new return value formats and `Enum` types for relevant attributes. Import and use `Enum` classes (e.g., `MonitorType`) for comparisons.
gotcha The `UptimeKumaApi` connection must be explicitly disconnected using `api.disconnect()` or by utilizing a Python context manager (`with UptimeKumaApi(...) as api:`) to prevent the program from blocking indefinitely.
Fix: Always use a `with` statement for `UptimeKumaApi` instances or ensure `api.disconnect()` is called in a `finally` block or at the end of your script.
gotcha The library requires an active Uptime Kuma server with authentication enabled. You must provide the correct Uptime Kuma instance URL, username, and password to the `UptimeKumaApi` constructor and `login()` method.
Fix: Ensure your Uptime Kuma instance is running and accessible, authentication is configured, and pass valid credentials to the `UptimeKumaApi` initialization and `login()` call.

Install

pip install uptime-kuma-api Install stable version

Imports

UptimeKumaApi

from uptime_kuma_api import UptimeKumaApi

MonitorType
```
from uptime_kuma_api import MonitorType
```
Required for specifying monitor types (e.g., HTTP, PING).

Quickstart

This quickstart demonstrates how to connect to an Uptime Kuma instance, log in, retrieve existing monitors, and add a new HTTP monitor using a context manager for automatic disconnection. Ensure your Uptime Kuma URL, username, and password are set as environment variables or replaced directly in the script.

import os
from uptime_kuma_api import UptimeKumaApi, MonitorType

UPTIME_KUMA_URL = os.environ.get('UPTIME_KUMA_URL', 'http://localhost:3001')
UPTIME_KUMA_USERNAME = os.environ.get('UPTIME_KUMA_USERNAME', 'admin')
UPTIME_KUMA_PASSWORD = os.environ.get('UPTIME_KUMA_PASSWORD', 'your_password')

try:
    with UptimeKumaApi(UPTIME_KUMA_URL) as api:
        api.login(UPTIME_KUMA_USERNAME, UPTIME_KUMA_PASSWORD)
        print(f"Successfully logged in to Uptime Kuma at {UPTIME_KUMA_URL}")

        # Example: Get all monitors
        monitors = api.get_monitors()
        if monitors:
            print(f"Found {len(monitors)} monitors:")
            for monitor in monitors:
                print(f"- ID: {monitor['id']}, Name: {monitor['name']}, Type: {monitor['type']}")
        else:
            print("No monitors found. Adding a new one...")
            # Example: Add a new HTTP monitor
            new_monitor_name = "My Website"
            new_monitor_url = "https://example.com"
            result = api.add_monitor(type=MonitorType.HTTP, name=new_monitor_name, url=new_monitor_url, interval=60)
            print(f"Added new monitor '{new_monitor_name}': {result}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →