Metadata-Version: 2.4
Name: uptime-kuma-api-ng
Version: 1.9.0
Summary: A python wrapper for the Uptime Kuma WebSocket API (maintained fork, Uptime Kuma 2.x compatible)
Author: Lucas Held
Maintainer-email: Arpad Rozsas <rozsasarpi@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/rozsasarpi/uptime-kuma-api
Project-URL: Documentation, https://rozsasarpi.github.io/uptime-kuma-api/
Project-URL: Repository, https://github.com/rozsasarpi/uptime-kuma-api
Project-URL: Issues, https://github.com/rozsasarpi/uptime-kuma-api/issues
Project-URL: Changelog, https://github.com/rozsasarpi/uptime-kuma-api/releases
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-socketio[client]>=5.16.2
Requires-Dist: packaging
Dynamic: license-file

# uptime-kuma-api-ng

[![PyPI](https://img.shields.io/pypi/v/uptime-kuma-api-ng)](https://pypi.org/project/uptime-kuma-api-ng/)
[![Docs](https://img.shields.io/badge/docs-latest-blue)](https://rozsasarpi.github.io/uptime-kuma-api/)
[![CodeQL](https://github.com/rozsasarpi/uptime-kuma-api/actions/workflows/codeql.yml/badge.svg)](https://github.com/rozsasarpi/uptime-kuma-api/actions/workflows/codeql.yml)
[![Security scan](https://github.com/rozsasarpi/uptime-kuma-api/actions/workflows/security.yml/badge.svg)](https://github.com/rozsasarpi/uptime-kuma-api/actions/workflows/security.yml)
[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/rozsasarpi/uptime-kuma-api/badge)](https://securityscorecards.dev/viewer/?uri=github.com/rozsasarpi/uptime-kuma-api)

> **Maintained fork** of [lucasheld/uptime-kuma-api](https://github.com/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](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](https://github.com/louislam/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:

| Uptime Kuma      | uptime-kuma-api-ng |
|------------------|---------------------|
| 1.21.3 - current | current `uptime-kuma-api-ng` releases (this fork; detects the connected server's version at runtime and adapts, so one package version covers the whole range -- see [CHANGELOG.md](CHANGELOG.md) for exactly which release each fix landed in) |
| 1.21.3 - 1.23.2  | 1.0.0 - 1.2.1 (original, unmaintained upstream) |
| 1.17.0 - 1.21.2  | 0.1.0 - 0.13.0 (original, unmaintained upstream) |

CI runs the real test suite against Uptime Kuma 1.21.3, 1.23.13, 2.0.0, and
current 2.x stable on every push -- see [AGENTS.md](AGENTS.md) for the exact
protocol differences this client adapts to across that range.

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](https://codeql.github.com/) static analysis (GitHub's own SAST).
- [Bandit](https://bandit.readthedocs.io/) for Python-specific security anti-patterns.
- [pip-audit](https://github.com/pypa/pip-audit) checking dependencies against the OSV
  vulnerability database, plus [Dependabot](https://docs.github.com/en/code-security/dependabot)
  opening PRs when a dependency has a fix available.
- [OpenSSF Scorecard](https://securityscorecards.dev/) 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
---
This fork is published on the [Python Package Index (PyPI)](https://pypi.org/project/uptime-kuma-api-ng/)
as `uptime-kuma-api-ng` (the original `uptime-kuma-api` name is taken by the unmaintained upstream
project). The importable module is still `uptime_kuma_api` — only your `pip install` line changes.

You can install it using pip:

```
pip install uptime-kuma-api-ng
```

Documentation
---
The API Reference is available at [rozsasarpi.github.io/uptime-kuma-api](https://rozsasarpi.github.io/uptime-kuma-api/).

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.

```python
>>> 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:

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

```python
>>> api.disconnect()
```

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

```python
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"
    )
```
