https://github.com/wvogel/uptime-kuma-api

Lightweight read-only REST API sidecar for Uptime Kuma — exposes monitor metadata and latest heartbeats to external dashboards
https://github.com/wvogel/uptime-kuma-api

api docker fastapi mariadb monitoring proxy python read-only rest-api self-hosted sidecar uptime-kuma

Last synced: 14 days ago
JSON representation

Lightweight read-only REST API sidecar for Uptime Kuma — exposes monitor metadata and latest heartbeats to external dashboards

• Host: GitHub
• URL: https://github.com/wvogel/uptime-kuma-api
• Owner: wvogel
• License: mit
• Created: 2026-04-06T06:52:54.000Z (2 months ago)
• Default Branch: main
• Last Pushed: 2026-04-18T15:49:20.000Z (about 2 months ago)
• Last Synced: 2026-04-18T17:28:57.902Z (about 2 months ago)
• Topics: api, docker, fastapi, mariadb, monitoring, proxy, python, read-only, rest-api, self-hosted, sidecar, uptime-kuma
• Language: Python
• Homepage:
• Size: 35.2 KB
• Stars: 1
• Watchers: 0
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

          
# uptime-kuma-api

Lightweight read-only API proxy for [Uptime Kuma](https://github.com/louislam/uptime-kuma) monitor data. Designed to be deployed as a sidecar container alongside each Uptime Kuma instance. Part of [uptime-kuma-status](https://github.com/wvogel/uptime-kuma-status).

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

[![Python](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/)

[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688.svg)](https://fastapi.tiangolo.com/)

[![Docker](https://img.shields.io/badge/docker-ghcr.io-2496ED.svg?logo=docker&logoColor=white)](https://github.com/wvogel/uptime-kuma-api/pkgs/container/uptime-kuma-api)

[![Uptime Kuma](https://img.shields.io/badge/Uptime%20Kuma-compatible-5CDD8B.svg)](https://github.com/louislam/uptime-kuma)

[![Changelog](https://img.shields.io/badge/changelog-keepachangelog-orange.svg)](CHANGELOG.md)

[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

## Architecture

![Architecture](docs/architecture-en.svg)

## Quick Start

Add to your Uptime Kuma `docker-compose.yml`:

```yaml

  uptime-kuma-api:

    image: ghcr.io/wvogel/uptime-kuma-api:latest

    restart: unless-stopped

    environment:

      DB_HOST: mariadb        # your MariaDB service name

      DB_NAME: kuma           # database name

      DB_USER: kuma           # database user

      DB_PASS:      # database password

      API_KEY:  # generated by uptime-status admin

    healthcheck:

      test: ["CMD", "curl", "-f", "http://127.0.0.1:80/health"]

      interval: 30s

      retries: 3

      start_period: 10s

      timeout: 5s

    networks:

      - default

      - shared-npm

```

## Environment Variables

| Variable | Default | Description |

|----------|---------|-------------|

| `DB_HOST` | `mariadb` | MariaDB hostname |

| `DB_PORT` | `3306` | MariaDB port |

| `DB_NAME` | `kuma` | Database name |

| `DB_USER` | `kuma` | Database user |

| `DB_PASS` | *required* | Database password |

| `API_KEY` | *required* | API key for authentication |

| `ALLOWED_RANGES` | *(empty)* | Comma-separated CIDR ranges for IP filtering (e.g. `10.0.0.0/8,172.16.0.0/12`) |

## Endpoints

| Endpoint | Auth | Description |

|----------|------|-------------|

| `GET /health` | No | Healthcheck, returns `{"status": "ok"}` |

| `GET /api/monitors` | `X-API-Key` | Returns all monitors + latest heartbeats |

## Security

- API key validated via constant-time comparison (`hmac.compare_digest`)

- Optional IP range filtering via `ALLOWED_RANGES` (CIDR notation)

- `X-Forwarded-For` header respected for IP detection behind reverse proxies

- Read-only database access

## License

MIT