Registry / devops / uptime-kuma-api

uptime-kuma-api

library1.2.1pypypi✓ verified 24d ago

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.

devops http-networking observability

pip install uptime-kuma-api

github ↗package ↗

INSTALL

IMPORT

SIG · UPTIME-KUMA-API

uptime-kuma-api

devopspythonv1.2.1

Install

3.8s avg

Import

618ms

Disk

25MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.2.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.644s · 26.7MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.8s · import 0.592s · 27MB

25MB installed

● package 25MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

UptimeKumaApi

✓ from uptime_kuma_api import UptimeKumaApi

MonitorType

✓ from uptime_kuma_api import MonitorType

Required for specifying monitor types (e.g., HTTP, PING).

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}")

Debug

Known issues

breakingVersion 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+.

affects: <1.0.0

breakingAPI 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.

affects: <1.0.0

breakingWith 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()`.

affects: <1.0.0

breakingFrom 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.

affects: <1.0.0

gotchaThe `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.

affects: All versions

gotchaThe 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'uptime_kuma_api'

The `uptime-kuma-api` library is not installed in your Python environment or the import statement uses an incorrect module name.

fix

First, install the library: `pip install uptime-kuma-api`. Then, use the correct import: `from uptime_kuma_api import UptimeKumaAPI`.

UptimeKumaAPIError: Failed to login: Invalid username or password.

The username or password provided to initialize the `UptimeKumaAPI` client is incorrect for your Uptime Kuma instance.

fix

Verify that the `username` and `password` passed to `UptimeKumaAPI(host, username, password)` exactly match a valid user's credentials in your Uptime Kuma instance.

websocket.exceptions.WebSocketConnectionClosedException

The WebSocket connection to the Uptime Kuma instance could not be established or was prematurely closed, often due to an incorrect host URL, an unreachable instance, or network issues.

fix

Ensure your Uptime Kuma instance is running and accessible. Verify the `host` parameter includes the correct scheme (e.g., `http://localhost:3001`, `https://your-kuma.com`, or `wss://your-kuma.com/socket.io`) and that no firewall is blocking the connection.

UptimeKumaAPIError: The field `name` is required.

You attempted to add or edit a monitor without providing a mandatory parameter, such as the `name` for the monitor, which is required by the Uptime Kuma API.

fix

When calling methods like `add_monitor` or `edit_monitor`, ensure all required parameters (e.g., `name`, `type`, `url` for a standard HTTP monitor) are provided with valid values, as specified by the Uptime Kuma API documentation.

Upgrade

Version history

1.2.1latest on PyPI · released Sep 26, 2023

Audit

Dependencies

python-socketiorequiredCore dependency for WebSocket communication with Uptime Kuma.

packagingrequiredUsed for version parsing and compatibility checks.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/lucasheld/uptime-kuma-api ↗

packagehttps://pypi.org/project/uptime-kuma-api/ ↗