A comprehensive Python client for Uptime Kuma's REST and Socket.io APIs. This library provides both synchronous REST operations and asynchronous real-time monitoring capabilities.
Uptime Kuma's API is primarily designed for the application's own use and is not officially supported for third-party integrations. Breaking changes may occur between versions without prior notice. Use at your own risk.
- 🔄 Dual API Support: Both REST endpoints and real-time Socket.io communication
- ⚡ Asynchronous Operations: Full async support for real-time events
- 📊 Monitor Management: Create, edit, delete, pause/resume monitors
- 🔔 Real-time Events: Callbacks for heartbeats, monitor updates, uptime changes
- 🔐 Multiple Authentication: Username/password, API key, and JWT token support
- 📈 Status Page Integration: Get status page data and heartbeat information
- 🛠️ Notification Management: Configure and test notifications
- ⚙️ Settings Management: Access and modify server settings
pip install pykumaapi2Or install from source:
git clone https://github.com/emadomedher/pyKumaAPI.git
cd pykumaapi
pip install -r requirements.txt
pip install .from uptime_kuma_api import UptimeKumaClient
import asyncio
async def main():
# Initialize client
client = UptimeKumaClient(
base_url="http://localhost:3001",
username="your_username",
password="your_password"
)
try:
# Connect via Socket.io
connected = await client.connect()
if not connected:
print("Failed to connect")
return
# Login
login_result = await client.login("your_username", "your_password")
if not login_result.get("ok"):
print(f"Login failed: {login_result.get('msg')}")
return
print("Successfully connected to Uptime Kuma!")
# Get monitors
monitors = await client.get_monitor_list()
print(f"Monitors: {monitors}")
# Create a new monitor
monitor_data = {
"name": "My Website",
"type": "http",
"url": "https://example.com",
"interval": 60
}
result = await client.add_monitor(monitor_data)
print(f"Created monitor: {result}")
finally:
await client.disconnect()
asyncio.run(main())from uptime_kuma_api import UptimeKumaRESTClient
# Initialize REST client
client = UptimeKumaRESTClient(
base_url="http://localhost:3001",
username="your_username",
password="your_password"
)
try:
# Push monitor status
result = client.push_monitor_status(
push_token="your_push_token",
status="up",
msg="Service is running",
ping=150.5
)
print(f"Push result: {result}")
# Get status page
status_page = client.get_status_page("your-status-page-slug")
print(f"Status page: {status_page}")
finally:
client.close()from uptime_kuma_api import UptimeKumaClient
import asyncio
async def on_heartbeat(data):
"""Handle heartbeat events."""
print(f"Heartbeat: {data}")
async def on_monitor_update(data):
"""Handle monitor list updates."""
print(f"Monitor update: {data}")
async def main():
client = UptimeKumaClient(
base_url="http://localhost:3001",
username="your_username",
password="your_password"
)
# Register event handlers
client.on_heartbeat(on_heartbeat)
client.on_monitor_list_update(on_monitor_update)
await client.connect()
await client.login("username", "password")
# Keep the connection alive
await asyncio.sleep(300) # Monitor for 5 minutes
await client.disconnect()
asyncio.run(main())The main client that combines both REST and Socket.io functionality.
client = UptimeKumaClient(
base_url="http://localhost:3001", # Uptime Kuma instance URL
username="your_username", # Optional: username for auth
password="your_password", # Optional: password for auth
api_key="your_api_key", # Optional: API key for auth
token="jwt_token" # Optional: JWT token
)await connect() -> bool: Connect to Uptime Kuma via Socket.ioawait disconnect(): Disconnect from Socket.io
await login(username, password, token=None): Login via Socket.ioawait login_by_token(jwt_token): Login using JWT token
await add_monitor(monitor_data): Create a new monitorawait edit_monitor(monitor_data): Update an existing monitorawait delete_monitor(monitor_id): Delete a monitorawait pause_monitor(monitor_id): Pause a monitorawait resume_monitor(monitor_id): Resume a monitorawait get_monitor(monitor_id): Get monitor detailsawait get_monitor_beats(monitor_id, period=24): Get monitor heartbeat data
await add_notification(notification_data): Add a notificationawait delete_notification(notification_id): Delete a notificationawait test_notification(notification_data): Test a notification
await add_status_page(title, slug): Create a status pageawait save_status_page(slug, config, public_group_list): Save status page configawait delete_status_page(slug): Delete a status page
on_heartbeat(callback): Register heartbeat event callbackon_monitor_list_update(callback): Register monitor list update callbackon_uptime_update(callback): Register uptime update callback
REST API client for basic operations.
client = UptimeKumaRESTClient(
base_url="http://localhost:3001",
username="your_username", # Optional
password="your_password", # Optional
api_key="your_api_key" # Optional
)push_monitor_status(push_token, status="up", msg="OK", ping=None): Push monitor statusget_status_page(slug): Get status page dataget_status_page_heartbeat(slug): Get status page heartbeat dataget_metrics(): Get Prometheus metricsget_entry_page(): Get entry page information
Uptime Kuma supports various monitor types:
| Type | Description |
|---|---|
http |
HTTP/HTTPS website monitoring |
keyword |
Monitor for specific text content |
ping |
ICMP ping monitoring |
port |
TCP port monitoring |
dns |
DNS resolution monitoring |
push |
Push-based monitoring |
steam |
Steam game server monitoring |
docker |
Docker container monitoring |
The library supports multiple authentication methods:
- Username/Password: Traditional login credentials
- API Key: For metrics endpoint access
- JWT Token: For token-based authentication after initial login
from uptime_kuma_api import UptimeKumaClient
import asyncio
async def main():
client = UptimeKumaClient(base_url="http://localhost:3001")
try:
await client.connect()
result = await client.login("username", "password")
if not result.get("ok"):
print(f"Login failed: {result.get('msg')}")
return
# Your code here
except Exception as e:
print(f"Error: {e}")
finally:
await client.disconnect()See the examples/ directory for complete usage examples:
basic_monitoring.py: Basic monitor creation and managementreal_time_events.py: Real-time event handlingstatus_page_monitoring.py: Status page data retrievalnotification_setup.py: Notification configuration
git clone https://github.com/emadomedher/pyKumaAPI.git
cd pykumaapi
pip install -e ".[dev]"pytest# Format code
black .
# Lint code
flake8 .
# Type checking
mypy .- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
This library is not officially affiliated with or endorsed by the Uptime Kuma project. Uptime Kuma's API is internal and may change without notice. Use this library at your own risk.
- Initial release
- REST API client implementation
- Socket.io real-time client implementation
- Comprehensive monitor management
- Event handling system
- Multiple authentication methods