{"id":4316,"library":"uptime-kuma-api","title":"Uptime Kuma API Wrapper","description":"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.","status":"active","version":"1.2.1","language":"en","source_language":"en","source_url":"https://github.com/lucasheld/uptime-kuma-api","tags":["uptime kuma","monitoring","api wrapper","websocket","observability","system health"],"install":[{"cmd":"pip install uptime-kuma-api","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for WebSocket communication with Uptime Kuma.","package":"python-socketio"},{"reason":"Used for version parsing and compatibility checks.","package":"packaging"}],"imports":[{"symbol":"UptimeKumaApi","correct":"from uptime_kuma_api import UptimeKumaApi"},{"note":"Required for specifying monitor types (e.g., HTTP, PING).","symbol":"MonitorType","correct":"from uptime_kuma_api import MonitorType"}],"quickstart":{"code":"import os\nfrom uptime_kuma_api import UptimeKumaApi, MonitorType\n\nUPTIME_KUMA_URL = os.environ.get('UPTIME_KUMA_URL', 'http://localhost:3001')\nUPTIME_KUMA_USERNAME = os.environ.get('UPTIME_KUMA_USERNAME', 'admin')\nUPTIME_KUMA_PASSWORD = os.environ.get('UPTIME_KUMA_PASSWORD', 'your_password')\n\ntry:\n    with UptimeKumaApi(UPTIME_KUMA_URL) as api:\n        api.login(UPTIME_KUMA_USERNAME, UPTIME_KUMA_PASSWORD)\n        print(f\"Successfully logged in to Uptime Kuma at {UPTIME_KUMA_URL}\")\n\n        # Example: Get all monitors\n        monitors = api.get_monitors()\n        if monitors:\n            print(f\"Found {len(monitors)} monitors:\")\n            for monitor in monitors:\n                print(f\"- ID: {monitor['id']}, Name: {monitor['name']}, Type: {monitor['type']}\")\n        else:\n            print(\"No monitors found. Adding a new one...\")\n            # Example: Add a new HTTP monitor\n            new_monitor_name = \"My Website\"\n            new_monitor_url = \"https://example.com\"\n            result = api.add_monitor(type=MonitorType.HTTP, name=new_monitor_name, url=new_monitor_url, interval=60)\n            print(f\"Added new monitor '{new_monitor_name}': {result}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7+ before upgrading uptime-kuma-api to 1.0.0+.","message":"Version 1.0.0 dropped support for Python 3.6. Users must upgrade to Python 3.7 or higher.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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()`.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Uptime Kuma instance is running and accessible, authentication is configured, and pass valid credentials to the `UptimeKumaApi` initialization and `login()` call.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}