DOCSEARCHbyAlgolia
Submit Docs

Uptime-Kuma-Web-API

repository·main·Indexed 42 days ago

https://github.com/medaziz11/uptime-kuma-web-api

A REST API wrapper for Uptime Kuma that provides a standardized interface to interact with monitoring data using JWT authentication. It includes a FastAPI-based backend with Swagger UI documentation and supports deployment via Docker Compose.

Tokens
1.9K
Snippets
6
Records
7
Agent score
52%

What's inside Uptime-Kuma-Web-API

  1. Deploy Uptime-Kuma-Web-API using Docker Compose

    main

    You can deploy both Uptime Kuma and the REST API wrapper together using Docker Compose. This setup ensures the API can communicate with the Kuma container over the internal Docker network.

    Important Setup Step: To use the provided example, you must run Kuma first, create your Kuma username and password, and then run the compose file. This ensures the credentials provided in the environment variables match an existing user in Kuma.

    version: "3.9"
services:
  kuma:
    container_name: uptime-kuma
    image: louislam/uptime-kuma:latest
    ports:
      - "3001:3001"
    restart: always
    volumes:
      - uptime-kuma:/app/data

  api:
    container_name: backend
    image: medaziz11/uptimekuma_restapi
    volumes:
      - api:/db
    restart: always
    environment:
      - KUMA_SERVER=http://kuma:3001
      - KUMA_USERNAME=test
      - KUMA_PASSWORD=123test.
      - ADMIN_PASSWORD=admin
    depends_on:
      - kuma
    ports:
      - "8000:8000"

volumes:
  uptime-kuma:
  api:

  2. Configure Uptime-Kuma-Web-API environment variables

    main

    To connect the REST API wrapper to your Uptime Kuma instance, you must define specific environment variables. The API uses these to authenticate with Kuma and to manage its own access control.

    Required Variables

    • KUMA_SERVER: The URL of your Uptime Kuma instance (e.g., https://uptime.example.com).
    • KUMA_USERNAME: The username of your Uptime Kuma user.
    • KUMA_PASSWORD: The password of your Uptime Kuma user.
    • ADMIN_PASSWORD: The password used to access the REST API itself.

    Note: You must define ADMIN_PASSWORD. Once defined, you access the API using the username admin and the password you provided.

    Optional Variables

    • ACCESS_TOKEN_EXPIRATION: The validity duration of the access token in minutes. Defaults to 8 days.
    • SECRET_KEY: A secret value used to encode JSON Web Tokens (JWTs).

  4. Configure the Uptime-Kuma-Web-API via Docker Compose

    main

    The api service can be deployed using Docker Compose. It requires connection details for an existing Uptime Kuma instance and credentials for authentication. You can configure these using environment variables.

    Note: To ensure the example works, you must run Uptime Kuma first, create your Kuma username and password, and then run the compose file.

    services:
  api:
    build: .
    environment:
      - KUMA_SERVER=${KUMA_SERVER:-http://kuma:3001}
      - KUMA_USERNAME=${KUMA_USERNAME:-test}
      - KUMA_PASSWORD=${KUMA_PASSWORD:-123test.}
      - ADMIN_PASSWORD=${ADMIN_PASSWORD:-admin}
      - SECRET_KEY=${SECRET_KEY:-pO8WunLtrznm2i4NfOJ25BkG4sh4kYwN1FjzZp8O6E0}
    ports:
      - "8000:8000"

  5. Authenticate and call the REST API via CURL

    main

    The API uses JWT (JSON Web Tokens) for authentication. To interact with protected endpoints, you must first request an access token using your admin credentials, then include that token in the Authorization header as a Bearer token.

    This example demonstrates how to retrieve a token and then use it to fetch the list of monitors.

    # 1. Get the access token
TOKEN=$(curl -X -L 'POST' -H 'Content-Type: application/x-www-form-urlencoded' --data 'username=admin&password=admin' http://127.0.0.1:8000/login/access-token/ | jq -r ".access_token")

# 2. Use the token to call a protected endpoint
curl -L -H 'Accept: application/json' -H "Authorization: Bearer ${TOKEN}" http://127.0.0.1:8000/monitors/

  6. Explore the Uptime-Kuma-Web-API endpoints

    main

    The API is organized into several functional modules, each accessible via a specific URL prefix. You can explore the full interactive API documentation (Swagger UI) by navigating to the root URL of the service.

    ### Available API Prefixes

| Prefix | Tag | Description |
|--------|-----|-------------|
| `/users` | Users | User management |
| `/settings` | Settings | Configuration settings |
| `/database` | DataBase | Database operations |
| `/monitors` | Monitor | Monitor management |
| `/statuspages` | Status Page | Status page configuration |
| `/maintenance` | Maintenance | Maintenance mode settings |
| `/tags` | Tags | Tag management |
| `/cert_info` | Certification Info | Certificate information |
| `/info` | Informations | General information |
| `/ping` | Ping Average | Ping statistics |
| `/uptime` | Uptime | Uptime statistics |
| `/login` | Authentication | Authentication and login |

  7. Reference environment variables for the API service

    main

    The following environment variables are used to configure the api service behavior and connectivity to Uptime Kuma.

    KUMA_SERVER        # The URL of the Uptime Kuma instance (default: http://kuma:3001)
KUMA_USERNAME      # The username for the Uptime Kuma instance (default: test)
KUMA_PASSWORD      # The password for the Uptime Kuma instance (default: 123test.)
ADMIN_PASSWORD     # The password for the API's own admin account (default: admin)
SECRET_KEY         # A random 32-bit URL-safe string used for security (default: pO8WunLtrznm2i4NfOJ25BkG4sh4kYwN1FjzZp8O6E0)