mikkel/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab/uptime-kuma
History
Mikkel Georgsen 172087b463 Add Uptime Kuma helper script and monitors 
- Created ~/bin/kuma for managing monitors via Socket.IO API
- Uses uptime-kuma-api Python library
- Added monitors: PBS, Forgejo, Technitium DNS
- Updated credentials with username/password for Socket.IO auth

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 23:04:51 +00:00
..
credentials Add Uptime Kuma helper script and monitors 2026-01-14 23:04:51 +00:00
kuma_api_doc.png Move Kuma API doc screenshot to uptime-kuma folder 2026-01-14 22:58:10 +00:00
README.md Move Kuma API doc screenshot to uptime-kuma folder 2026-01-14 22:58:10 +00:00

README.md

Uptime Kuma API

Overview

Authentication

source ~/.config/uptime-kuma/credentials
# Variables: KUMA_HOST, KUMA_PORT, KUMA_API_KEY

Use API key as password with empty username for Basic Auth:

curl -u ":$KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/metrics"

Or Bearer token:

curl -H "Authorization: Bearer $KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/api/entry-page"

REST API Endpoints

Prometheus Metrics

curl -u ":$KUMA_API_KEY" "http://$KUMA_HOST:$KUMA_PORT/metrics"

Push Monitor (Passive Checks)

For push-type monitors, update status via URL:

# Basic
curl "http://$KUMA_HOST:$KUMA_PORT/api/push/<pushToken>"

# With parameters
curl "http://$KUMA_HOST:$KUMA_PORT/api/push/<pushToken>?status=up&msg=OK&ping=50"

Parameters:

  • status - "up" or "down" (default: "up")
  • msg - Status message, ~250 chars max (default: "OK")
  • ping - Response time in ms

Status Page Data

# Get status page info (requires published status page)
curl "http://$KUMA_HOST:$KUMA_PORT/api/status-page/<slug>"

# Get heartbeats and uptime
curl "http://$KUMA_HOST:$KUMA_PORT/api/status-page/heartbeat/<slug>"

Status Badges

# Status badge (monitor must be in public status page group)
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/status"

# Uptime badge
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/uptime"
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/uptime/24h"
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/uptime/7d"

# Response time badge
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/ping"

# Certificate expiry badge
curl "http://$KUMA_HOST:$KUMA_PORT/api/badge/<monitor_id>/cert-exp"

Entry Page

curl "http://$KUMA_HOST:$KUMA_PORT/api/entry-page"

Limitations

The REST API is limited to:

  • Push monitor updates
  • Reading metrics/status
  • Badge generation

Full monitor management (create, edit, delete monitors) requires the Socket.IO API, which is more complex and uses WebSockets. For adding monitors, use the web UI at https://status.georgsen.dk.

Socket.IO API

Full monitor management (create, edit, delete) is available via Socket.IO. See kuma_api_doc.png for complete API documentation screenshot.

References