docker-infrastructure/uptime-kuma/API.md

# 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()
```

## 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