pocketsized/kumarestapi repository overview

⁠Kuma RestAPI Wrapper

Full details on the Website⁠

A REST API wrapper for Uptime Kuma⁠. Manage monitors, tags, notifications, proxies, Docker hosts, maintenance windows, and status pages with plain authenticated HTTP calls.

⁠Why this exists

Uptime Kuma's own REST endpoints are limited to badge images, /metrics, and status page data. There is no REST API for monitors, tags, notifications, or maintenance. Those only exist over its Socket.IO API, which also only authenticates with a username and password, not an API key.

This image bridges the two: it holds one persistent, logged-in Socket.IO session internally, and exposes a conventional REST API on top of it. Every request to the wrapper is authenticated with a real Uptime Kuma API key over HTTP Basic Auth.

REST client  --Basic Auth, API key-->  kuma-restapi-wrapper  --Socket.IO, user/pass-->  Uptime Kuma

⁠Quick start

1. Create an API key in Uptime Kuma Settings → API Keys → Add API Key.

2. Run the container

docker run -d \
  --name kuma-restapi-wrapper \
  -p 3100:3100 \
  -e KUMA_URL=http://uptime-kuma:3001 \
  -e KUMA_USERNAME=username \
  -e KUMA_PASSWORD=password \
  pocketsized/kumarestapi

3. Call it

curl -u api:your_api_key http://uptimekuma:3100/monitors

⁠docker-compose

services:
  kuma-restapi-wrapper:
    image: pocketsized/kumarestapi
    restart: unless-stopped
    ports:
      - "3100:3100"
    environment:
      KUMA_URL: http://uptime-kuma:3001
      KUMA_USERNAME: username
      KUMA_PASSWORD: password
      # KUMA_TOTP_SECRET: your_2fa_secret   # only if 2FA is enabled
      # APIKEY_CACHE_TTL: "30"

KUMA_URL needs to resolve from inside the container — use the service name if Uptime Kuma runs in the same Docker network, or host.docker.internal if it runs on the host.

⁠Environment variables

⁠API overview

All routes are exposed via the Swagger UI. Anything you want as the username and your Uptime Kuma API key as the password.

⁠Image details

• Multi-stage build on node:24-alpine; only production dependencies ship in the final image.
• Runs as a non-root user.
• Built-in HEALTHCHECK polling /healthz every 30 seconds.
• Dependencies install with --ignore-scripts; the runtime image strips npm, npx, and corepack entirely.

⁠Tags

• latest — most recent stable build
• x.y.z — pinned releases

⁠Links

• More Info: Website⁠
• Uptime Kuma: github.com/louislam/uptime-kuma⁠