uptime-kuma-api-ng

Maintained fork of lucasheld/uptime-kuma-api, which appears abandoned (13 open PRs, 23 open issues, none merged/closed since 2023 as of this fork). Published as uptime-kuma-api-ng on PyPI since the original name is taken; the importable module is still uptime_kuma_api, so only your pip install line changes. Fixes add_monitor()/edit_monitor() against Uptime Kuma 2.x (missing conditions field) plus a delete_monitor() type bug. See MODERNIZATION_PLAN.md for deferred, larger-scope work (full 2.x audit, tests, CI, upstream PR/issue triage).

Maintenance model: this fork is maintained primarily by an AI coding agent (Claude), under human supervision, not by a human reading every line. Changes are scoped, reviewed, and merged with that in mind. There is no warranty and no guarantee of correctness, security, or continued maintenance — use at your own risk, pin a version, and review the diff before upgrading. Issues and PRs are welcome and will be triaged and reviewed (by the human maintainer and/or AI) before merging, same as any other project — being AI-assisted doesn't mean auto-merged.

uptime-kuma-api

A wrapper for the Uptime Kuma Socket.IO API

uptime-kuma-api is a Python wrapper for the Uptime Kuma Socket.IO API.

This package was developed to configure Uptime Kuma with Ansible. The Ansible collection can be found at https://github.com/lucasheld/ansible-uptime-kuma.

Python version 3.7+ is required.

Supported Uptime Kuma versions:

Security

This client never logs credentials (no print/logging calls anywhere in the library) and sends your username/password/token only to the Uptime Kuma server URL you provide, over the connection you configure. TLS verification is on by default.

Ongoing scanning, all free and running on every push/PR:

• CodeQL static analysis (GitHub's own SAST).
• Bandit for Python-specific security anti-patterns.
• pip-audit checking dependencies against the OSV vulnerability database, plus Dependabot opening PRs when a dependency has a fix available.
• OpenSSF Scorecard for overall repo security posture (branch protection, pinned dependencies, SAST coverage, etc.) — this one reports a 0-10 score, not a pass/fail; click the badge for the live breakdown.

Found a real security issue? Please open a GitHub issue — there's no dedicated security contact for this fork.

Installation

uptime-kuma-api is available on the Python Package Index (PyPI).

You can install it using pip:

pip install uptime-kuma-api

Documentation

The API Reference is available on Read the Docs.

Example

Once you have installed the python package, you can use it to communicate with an Uptime Kuma instance.

To do so, import UptimeKumaApi from the library and specify the Uptime Kuma server url (e.g. 'http://127.0.0.1:3001'), username and password to initialize the connection.

>>> from uptime_kuma_api import UptimeKumaApi, MonitorType
>>> api = UptimeKumaApi('INSERT_URL')
>>> api.login('INSERT_USERNAME', 'INSERT_PASSWORD')

Now you can call one of the existing methods of the instance. For example create a new monitor:

>>> result = api.add_monitor(type=MonitorType.HTTP, name="Google", url="https://google.com")
>>> print(result)
{'msg': 'Added Successfully.', 'monitorID': 1}

At the end, the connection to the API must be disconnected so that the program does not block.

>>> api.disconnect()

With a context manager, the disconnect method is called automatically:

from uptime_kuma_api import UptimeKumaApi, MonitorType

with UptimeKumaApi('INSERT_URL') as api:
    api.login('INSERT_USERNAME', 'INSERT_PASSWORD')
    api.add_monitor(
        type=MonitorType.HTTP,
        name="Google",
        url="https://google.com"
    )