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

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:

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:

export UPTIME_KUMA_USERNAME="your_username"
export UPTIME_KUMA_PASSWORD="your_password"

3. Make Script Executable

chmod +x /home/poprhythm/docker-infrastructure/uptime-kuma/manage_monitors.py

Usage

List All Monitors

./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:

./manage_monitors.py add --name "My Service" --url "https://myservice.com" --type http

TCP Port Monitor:

./manage_monitors.py add --name "PostgreSQL" --url "192.168.1.100:5432" --type tcp

Ping Monitor:

./manage_monitors.py add --name "Router" --url "192.168.1.1" --type ping

Custom Interval (default is 60 seconds):

./manage_monitors.py add --name "Critical Service" --url "https://critical.com" --interval 30

Update a Monitor

# 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

./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):

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:

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:

pip3 install uptime-kuma-api
# Or with sudo if needed:
sudo pip3 install uptime-kuma-api

Advanced Usage

Using as a Python Module

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 for comprehensive tag documentation.

Quick Tag Commands

Tag a new monitor:

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

./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:

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

References

• Uptime Kuma API Keys Documentation
• Uptime Kuma API Documentation
• uptime-kuma-api Python Package
• uptime-kuma-api Documentation

Web UI Access

• URL: https://uptime.kolpacksoftware.com
• Settings: Click gear icon → API Keys
• Monitor Management: Dashboard → Add/Edit monitors via UI