poprhythm
a6c4302c00
Complete documentation for monitor and tag management workflows: New documentation: - README.md: Quick reference and complete workflow guide - TAG_MANAGEMENT.md: Comprehensive tag management strategies - tag_monitor.sh: Quick CLI script to tag monitors Updated documentation: - API.md: Added tag management section with quick reference Coverage: - Adding monitors with tags (complete workflow) - Updating and deleting monitors - Tag management strategies and patterns - Common tagging patterns by service type - Troubleshooting guide - Best practices and maintenance tasks All common operations are now documented with examples.
257 lines
6.2 KiB
Markdown
257 lines
6.2 KiB
Markdown
# Uptime Kuma API Documentation
|
|
|
|
## Overview
|
|
|
|
Uptime Kuma provides a Socket.IO-based API for programmatic monitor management. The REST API does **not** support monitor CRUD operations - you must use the Socket.IO API via the `uptime-kuma-api` Python package.
|
|
|
|
## Setup
|
|
|
|
### 1. Install Python Package
|
|
|
|
```bash
|
|
pip3 install uptime-kuma-api
|
|
```
|
|
|
|
**Requirements:** Python 3.7+
|
|
|
|
### 2. Create API Credentials
|
|
|
|
#### Option A: API Key (Recommended)
|
|
|
|
1. Access Uptime Kuma web UI: https://uptime.kolpacksoftware.com
|
|
2. Navigate to **Settings → API Keys**
|
|
3. Click **Generate** to create a new API key
|
|
4. Set a descriptive name (e.g., "CLI Management")
|
|
5. Set expiry (or "Never expire")
|
|
6. **Copy the key immediately** (shown only once)
|
|
7. Store securely in environment variable:
|
|
|
|
```bash
|
|
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
|
```
|
|
|
|
**Important:** Once the first API key is created, basic authentication is permanently disabled for supported endpoints.
|
|
|
|
#### Option B: Username/Password
|
|
|
|
Use existing Uptime Kuma login credentials:
|
|
|
|
```bash
|
|
export UPTIME_KUMA_USERNAME="your_username"
|
|
export UPTIME_KUMA_PASSWORD="your_password"
|
|
```
|
|
|
|
### 3. Make Script Executable
|
|
|
|
```bash
|
|
chmod +x /home/poprhythm/docker-infrastructure/uptime-kuma/manage_monitors.py
|
|
```
|
|
|
|
## Usage
|
|
|
|
### List All Monitors
|
|
|
|
```bash
|
|
./manage_monitors.py list
|
|
```
|
|
|
|
Output:
|
|
```
|
|
ID Name Type URL
|
|
------------------------------------------------------------------------------------------------
|
|
1 Example Service http https://example.com
|
|
2 Database Health tcp 192.168.1.100:5432
|
|
3 Gateway Ping ping 192.168.1.1
|
|
```
|
|
|
|
### Add a Monitor
|
|
|
|
**HTTP/HTTPS Monitor:**
|
|
```bash
|
|
./manage_monitors.py add --name "My Service" --url "https://myservice.com" --type http
|
|
```
|
|
|
|
**TCP Port Monitor:**
|
|
```bash
|
|
./manage_monitors.py add --name "PostgreSQL" --url "192.168.1.100:5432" --type tcp
|
|
```
|
|
|
|
**Ping Monitor:**
|
|
```bash
|
|
./manage_monitors.py add --name "Router" --url "192.168.1.1" --type ping
|
|
```
|
|
|
|
**Custom Interval (default is 60 seconds):**
|
|
```bash
|
|
./manage_monitors.py add --name "Critical Service" --url "https://critical.com" --interval 30
|
|
```
|
|
|
|
### Update a Monitor
|
|
|
|
```bash
|
|
# Update name
|
|
./manage_monitors.py update --id 123 --name "New Name"
|
|
|
|
# Update URL
|
|
./manage_monitors.py update --id 123 --url "https://newurl.com"
|
|
|
|
# Update interval
|
|
./manage_monitors.py update --id 123 --interval 300
|
|
|
|
# Update multiple fields
|
|
./manage_monitors.py update --id 123 --name "Updated" --url "https://updated.com" --interval 120
|
|
```
|
|
|
|
### Delete a Monitor
|
|
|
|
```bash
|
|
./manage_monitors.py delete --id 123
|
|
```
|
|
|
|
## Monitor Types
|
|
|
|
| Type | Description | URL Format |
|
|
|------|-------------|------------|
|
|
| `http` | HTTP/HTTPS endpoint | `https://example.com` or `http://example.com` |
|
|
| `tcp` | TCP port check | `hostname:port` or `ip:port` |
|
|
| `ping` | ICMP ping | `hostname` or `ip` |
|
|
| `dns` | DNS resolution | `example.com` |
|
|
| `docker` | Docker container | Container name or ID |
|
|
|
|
## Authentication
|
|
|
|
The script checks for credentials in the following order:
|
|
|
|
1. `UPTIME_KUMA_API_KEY` environment variable (preferred)
|
|
2. `UPTIME_KUMA_USERNAME` and `UPTIME_KUMA_PASSWORD` environment variables
|
|
|
|
To persist credentials, add to your shell profile (`~/.bashrc` or `~/.zshrc`):
|
|
|
|
```bash
|
|
export UPTIME_KUMA_API_KEY="uk1_your_api_key_here"
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### "No credentials provided" Error
|
|
|
|
**Problem:** Script cannot find API credentials.
|
|
|
|
**Solution:** Set environment variables before running:
|
|
```bash
|
|
export UPTIME_KUMA_API_KEY="uk1_your_key"
|
|
./manage_monitors.py list
|
|
```
|
|
|
|
### Connection Refused
|
|
|
|
**Problem:** Cannot connect to Uptime Kuma instance.
|
|
|
|
**Solution:**
|
|
1. Verify service is running: `docker ps | grep uptime-kuma`
|
|
2. Check URL in script matches web UI access
|
|
3. Ensure SSL certificate is valid (or use `verify=False` in script for self-signed)
|
|
|
|
### "Monitor not found" Error
|
|
|
|
**Problem:** Monitor ID doesn't exist.
|
|
|
|
**Solution:** Run `./manage_monitors.py list` to see all valid monitor IDs.
|
|
|
|
### Import Error: uptime_kuma_api
|
|
|
|
**Problem:** Python package not installed.
|
|
|
|
**Solution:**
|
|
```bash
|
|
pip3 install uptime-kuma-api
|
|
# Or with sudo if needed:
|
|
sudo pip3 install uptime-kuma-api
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Using as a Python Module
|
|
|
|
```python
|
|
from uptime_kuma_api import UptimeKumaApi, MonitorType
|
|
|
|
# Connect
|
|
api = UptimeKumaApi("https://uptime.kolpacksoftware.com")
|
|
api.login_by_token("uk1_your_api_key")
|
|
|
|
# Get all monitors
|
|
monitors = api.get_monitors()
|
|
|
|
# Add monitor
|
|
api.add_monitor(
|
|
type=MonitorType.HTTP,
|
|
name="My Service",
|
|
url="https://example.com",
|
|
interval=60
|
|
)
|
|
|
|
# Edit monitor
|
|
monitor = api.get_monitor(1)
|
|
monitor['name'] = "Updated Name"
|
|
api.edit_monitor(1, **monitor)
|
|
|
|
# Delete monitor
|
|
api.delete_monitor(1)
|
|
|
|
# Always disconnect
|
|
api.disconnect()
|
|
```
|
|
|
|
## Tag Management
|
|
|
|
Tags help organize monitors by category. See [TAG_MANAGEMENT.md](TAG_MANAGEMENT.md) for comprehensive tag documentation.
|
|
|
|
### Quick Tag Commands
|
|
|
|
**Tag a new monitor:**
|
|
```bash
|
|
# After creating a monitor, tag it quickly
|
|
./tag_monitor.sh MONITOR_ID TAG_ID [TAG_ID...]
|
|
|
|
# Example: Tag monitor 15 as application + web
|
|
./tag_monitor.sh 15 3 4
|
|
```
|
|
|
|
**View all tags:**
|
|
```bash
|
|
./check_tags.py
|
|
```
|
|
|
|
**Common Tag IDs:**
|
|
- 1=hardware, 2=monitoring, 3=application, 4=web, 5=database
|
|
- 6=media, 7=infrastructure, 8=storage, 9=virtualization, 10=vm
|
|
|
|
**Full workflow for adding a tagged monitor:**
|
|
```bash
|
|
# 1. Add monitor and note the ID
|
|
./manage_monitors.py add --name "New Service" --url "https://example.com"
|
|
./manage_monitors.py list | grep "New Service"
|
|
|
|
# 2. Tag it
|
|
./tag_monitor.sh 16 3 4 # application + web
|
|
|
|
# 3. Verify
|
|
./check_tags.py | grep "New Service"
|
|
```
|
|
|
|
For detailed tagging strategies and workflows, see **[TAG_MANAGEMENT.md](TAG_MANAGEMENT.md)**.
|
|
|
|
## References
|
|
|
|
- [Uptime Kuma API Keys Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Keys)
|
|
- [Uptime Kuma API Documentation](https://github.com/louislam/uptime-kuma/wiki/API-Documentation)
|
|
- [uptime-kuma-api Python Package](https://github.com/lucasheld/uptime-kuma-api)
|
|
- [uptime-kuma-api Documentation](https://uptime-kuma-api.readthedocs.io/)
|
|
|
|
## Web UI Access
|
|
|
|
- **URL:** https://uptime.kolpacksoftware.com
|
|
- **Settings:** Click gear icon → API Keys
|
|
- **Monitor Management:** Dashboard → Add/Edit monitors via UI
|