mikkel/homelab
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
homelab/uptime-kuma/README.md
Mikkel Georgsen ce8c00aa1e Add Uptime Kuma API credentials and documentation 
- Added API key to uptime-kuma/credentials
- Created README.md with full API documentation
- Updated homelab-documentation.md and CLAUDE.md
- Added TODO to review monitors for missing services

REST API is limited (metrics, push monitors, badges).
Full monitor management requires Socket.IO/web UI.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-14 22:52:14 +00:00

2.5 KiB
Raw Blame History

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.

References