kuma

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 5, 2026 License: MIT Imports: 26 Imported by: 0

README

go-uptime-kuma-client

Test Status Go Report Card License

Go client library for the Uptime Kuma API using Socket.IO for real-time communication.

Installation

go get github.com/breml/go-uptime-kuma-client

Features

  • Monitor Management: HTTP, TCP, Ping, DNS, Redis, PostgreSQL, gRPC, Real Browser, and more
  • Notification Providers: Ntfy, Slack, Teams, Generic, and other notification types
  • Tag Management: Organize monitors with tags
  • Proxy Configuration: Route monitor requests through HTTP/HTTPS/SOCKS proxies
  • Maintenance Windows: Schedule maintenance periods
  • Status Pages: Create and manage public status pages
  • Real-time Updates: Socket.IO-based event system for state synchronization

Usage

Here's a complete example showing how to connect to Uptime Kuma, create a notification provider, and set up an HTTP monitor with notifications:

package main

import (
 "context"
 "log"

 kuma "github.com/breml/go-uptime-kuma-client"
 "github.com/breml/go-uptime-kuma-client/monitor"
 "github.com/breml/go-uptime-kuma-client/notification"
)

func main() {
 ctx := context.Background()

 // Create client and connect to Uptime Kuma
 client, err := kuma.New(ctx, "http://localhost:3001", "admin", "password")
 if err != nil {
  log.Fatal(err)
 }
 defer client.Disconnect()

 // Create a notification provider
 ntfyNotification := notification.Ntfy{
  Base: notification.Base{
   Name:     "My Ntfy Alert",
   IsActive: true,
  },
  NtfyDetails: notification.NtfyDetails{
   ServerURL:            "https://ntfy.sh",
   Topic:                "uptime-alerts",
   Priority:             5,
   AuthenticationMethod: "none",
  },
 }

 notificationID, err := client.CreateNotification(ctx, ntfyNotification)
 if err != nil {
  log.Fatal(err)
 }
 log.Printf("Created notification with ID: %d", notificationID)

 // Create an HTTP monitor that uses the notification
 httpMonitor := &monitor.HTTP{
  Base: monitor.Base{
   Name:            "Example Website",
   Interval:        60,
   NotificationIDs: []int64{notificationID},
  },
  HTTPDetails: monitor.HTTPDetails{
   URL:                 "https://example.com",
   Method:              "GET",
   AcceptedStatusCodes: []string{"200-299"},
  },
 }

 monitorID, err := client.CreateMonitor(ctx, httpMonitor)
 if err != nil {
  log.Fatal(err)
 }
 log.Printf("Created monitor with ID: %d", monitorID)
}

Documentation

Full documentation available at pkg.go.dev

API Coverage

This client supports the following Uptime Kuma features:

  • ✅ Monitors (all types)
  • ✅ Notifications
  • ✅ Tags
  • ✅ Proxies
  • ✅ Maintenance Windows
  • ✅ Status Pages

This is a work in progress, more Uptime Kuma features might be added in the future.

License

MIT License - see LICENSE for details

Documentation

Overview

Package kuma provides a Go client library for the Uptime Kuma API.

This library enables programmatic interaction with Uptime Kuma instances using Socket.IO for real-time communication. It supports comprehensive management of Uptime Kuma resources like monitors, notifications, etc.

Architecture

The library uses an entity-based package structure:

  • monitor/ - Monitor types (HTTP, TCP, DNS, gRPC, etc.)
  • notification/ - Notification provider types
  • tag/ - Tag management
  • proxy/ - Proxy configuration
  • maintenance/ - Maintenance windows
  • statuspage/ - Public status pages

The Client type maintains a local state cache synchronized via Socket.IO events, ensuring consistency with the Uptime Kuma server.

Basic Usage 

ctx := context.Background()
client, err := kuma.New(ctx, "http://localhost:3001", "username", "password")
if err != nil {
    log.Fatal(err)
}
defer client.Disconnect()

monitor := &monitor.HTTP{
    Base: monitor.Base{Name: "Example", Interval: 60},
    HTTPDetails: monitor.HTTPDetails{
        URL:    "https://example.com",
        Method: "GET",
    },
}
id, err := client.CreateMonitor(ctx, monitor)

Supported Monitor Types

HTTP, TCP, Ping, DNS, gRPC, Redis, PostgreSQL, Real Browser, and more. Each monitor type has its own struct with type-specific fields.

Type Conversion

The library provides base types (monitor.Base, notification.Base) that can be converted to specific types using the .As(target) method: 

base, _ := client.GetMonitor(ctx, id)
var httpMon monitor.HTTP
base.As(&httpMon)
Example 
ctx := context.Background()

// Using pre-initialized client from main_test.go connecting to Uptime
// Kuma running in Docker container.
//
// client, err := kuma.New(ctx, "http://localhost:3001", "admin", "password")
// if err != nil {
// 	log.Fatal(err)
// }
// defer func() { _ = client.Disconnect() }()

// Create a notification provider.
ntfyNotification := notification.Ntfy{
	Base: notification.Base{
		Name:     "My Ntfy Alert",
		IsActive: true,
	},
	NtfyDetails: notification.NtfyDetails{
		ServerURL:            "https://ntfy.sh",
		Topic:                "uptime-alerts",
		Priority:             5,
		AuthenticationMethod: "none",
	},
}

notificationID, err := client.CreateNotification(ctx, ntfyNotification)
if err != nil {
	log.Fatal(err)
}

retrievedNotification := notification.Ntfy{}
err = client.GetNotificationAs(ctx, notificationID, &retrievedNotification)
if err != nil {
	log.Fatal(err)
}

// Create an HTTP monitor that uses the notification.
httpMonitor := &monitor.HTTP{
	Base: monitor.Base{
		Name:            "Example Website",
		Interval:        60,
		NotificationIDs: []int64{notificationID},
		RetryInterval:   60,
	},
	HTTPDetails: monitor.HTTPDetails{
		URL:                 "https://example.com",
		Method:              "GET",
		AcceptedStatusCodes: []string{"200-299"},
	},
}

monitorID, err := client.CreateMonitor(ctx, httpMonitor)
if err != nil {
	log.Fatal(err)
}

retrievedMonitor := monitor.HTTP{}
err = client.GetMonitorAs(ctx, monitorID, &retrievedMonitor)
if err != nil {
	log.Fatal(err)
}

fmt.Println("Notification Topic:", retrievedNotification.Topic)
fmt.Println("HTTP Monitor URL:", retrievedMonitor.URL)

Output:

Notification Topic: uptime-alerts
HTTP Monitor URL: https://example.com

Index

Examples

Constants

View Source 
const (
	LogLevelDebug = utils.DEBUG
	LogLevelInfo  = utils.INFO
	LogLevelWarn  = utils.WARN
	LogLevelError = utils.ERROR
	LogLevelNone  = utils.NONE
)

Log level constants for configuring socket.io client logging verbosity.

Variables

View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound is returned when a requested resource is not found.

Functions

func LogLevel 

func LogLevel(level string) int

LogLevel converts a string log level to its corresponding integer constant.

Types

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client represents a connection to an Uptime Kuma server.

func New 

func New(ctx context.Context, baseURL string, username string, password string, opts ...Option) (*Client, error)

New creates a new Client connected to an Uptime Kuma server.

func (*Client) AddMonitorTag 

func (c *Client) AddMonitorTag(
	ctx context.Context,
	tagID int64,
	monitorID int64,
	value string,
) (*tag.MonitorTag, error)

AddMonitorTag adds a tag to a monitor with an optional value.

func (*Client) AddStatusPage 

func (c *Client) AddStatusPage(ctx context.Context, title string, slug string) error

AddStatusPage creates a new status page with the given title and slug.

func (*Client) CreateDockerHost 

func (c *Client) CreateDockerHost(ctx context.Context, config dockerhost.Config) (int64, error)

CreateDockerHost creates a new Docker host and returns its ID.

func (*Client) CreateMaintenance 

func (c *Client) CreateMaintenance(ctx context.Context, m *maintenance.Maintenance) (*maintenance.Maintenance, error)

CreateMaintenance creates a new maintenance window.

func (*Client) CreateMonitor 

func (c *Client) CreateMonitor(ctx context.Context, mon monitor.Monitor) (int64, error)

CreateMonitor creates a new monitor.

func (*Client) CreateNotification 

func (c *Client) CreateNotification(ctx context.Context, notif notification.Notification) (int64, error)

CreateNotification creates a new notification.

func (*Client) CreateProxy 

func (c *Client) CreateProxy(ctx context.Context, config proxy.Config) (int64, error)

CreateProxy creates a new proxy.

func (*Client) CreateTag 

func (c *Client) CreateTag(ctx context.Context, t tag.Tag) (int64, error)

CreateTag creates a new tag.

func (*Client) DeleteDockerHost 

func (c *Client) DeleteDockerHost(ctx context.Context, id int64) error

DeleteDockerHost deletes a Docker host by ID.

func (*Client) DeleteMaintenance 

func (c *Client) DeleteMaintenance(ctx context.Context, id int64) error

DeleteMaintenance deletes a maintenance window by ID.

func (*Client) DeleteMonitor 

func (c *Client) DeleteMonitor(ctx context.Context, monitorID int64) error

DeleteMonitor deletes a monitor by ID.

func (*Client) DeleteMonitorTag 

func (c *Client) DeleteMonitorTag(ctx context.Context, tagID int64, monitorID int64) error

DeleteMonitorTag removes all associations of a tag from a monitor (all values).

func (*Client) DeleteMonitorTagWithValue 

func (c *Client) DeleteMonitorTagWithValue(ctx context.Context, tagID int64, monitorID int64, value string) error

DeleteMonitorTagWithValue removes a specific tag association from a monitor by value.

func (*Client) DeleteNotification 

func (c *Client) DeleteNotification(ctx context.Context, id int64) error

DeleteNotification deletes a notification by ID.

func (*Client) DeleteProxy 

func (c *Client) DeleteProxy(ctx context.Context, id int64) error

DeleteProxy deletes a proxy by ID.

func (*Client) DeleteStatusPage 

func (c *Client) DeleteStatusPage(ctx context.Context, slug string) error

DeleteStatusPage deletes a status page by slug.

func (*Client) DeleteTag 

func (c *Client) DeleteTag(ctx context.Context, tagID int64) error

DeleteTag deletes a tag by ID. This also removes all monitor-tag associations for this tag via cascade delete.

func (*Client) Disconnect 

func (c *Client) Disconnect() error

Disconnect closes the connection to the Uptime Kuma server.

func (*Client) GetDockerHost 

func (c *Client) GetDockerHost(_ context.Context, id int64) (*dockerhost.DockerHost, error)

GetDockerHost returns a specific Docker host by ID.

func (*Client) GetDockerHostList 

func (c *Client) GetDockerHostList(_ context.Context) []dockerhost.DockerHost

GetDockerHostList returns all Docker hosts for the authenticated user.

func (*Client) GetMaintenance 

func (c *Client) GetMaintenance(ctx context.Context, id int64) (*maintenance.Maintenance, error)

GetMaintenance retrieves a specific maintenance window by ID.

func (*Client) GetMaintenanceStatusPage 

func (c *Client) GetMaintenanceStatusPage(ctx context.Context, maintenanceID int64) ([]int64, error)

GetMaintenanceStatusPage retrieves the status pages associated with a maintenance window.

func (*Client) GetMaintenances 

func (c *Client) GetMaintenances(_ context.Context) ([]maintenance.Maintenance, error)

GetMaintenances retrieves all maintenance windows from the client cache.

func (*Client) GetMonitor 

func (c *Client) GetMonitor(ctx context.Context, monitorID int64) (monitor.Base, error)

GetMonitor retrieves a specific monitor by ID.

func (*Client) GetMonitorAs 

func (c *Client) GetMonitorAs(ctx context.Context, monitorID int64, target any) error

GetMonitorAs retrieves a specific monitor by ID and converts it to the target type.

func (*Client) GetMonitorMaintenance 

func (c *Client) GetMonitorMaintenance(ctx context.Context, maintenanceID int64) ([]int64, error)

GetMonitorMaintenance retrieves the monitors associated with a maintenance window.

func (*Client) GetMonitorTags 

func (c *Client) GetMonitorTags(_ context.Context, monitorID int64) ([]tag.MonitorTag, error)

GetMonitorTags retrieves all tags for a specific monitor. This method uses the client's local state cache, which is kept synchronized via socket.io events. The cache is automatically updated by monitorList, updateMonitorIntoList, and deleteMonitorFromList events.

func (*Client) GetMonitors 

func (c *Client) GetMonitors(ctx context.Context) ([]monitor.Base, error)

GetMonitors retrieves all monitors for the authenticated user.

func (*Client) GetNotification 

func (c *Client) GetNotification(_ context.Context, id int64) (notification.Base, error)

GetNotification returns a specific notification by ID.

func (*Client) GetNotificationAs 

func (c *Client) GetNotificationAs(ctx context.Context, id int64, target any) error

GetNotificationAs returns a specific notification by ID and coverts it to the target type.

func (*Client) GetNotifications 

func (c *Client) GetNotifications(_ context.Context) []notification.Base

GetNotifications returns all notifications for the authenticated user.

func (*Client) GetProxy 

func (c *Client) GetProxy(_ context.Context, id int64) (*proxy.Proxy, error)

GetProxy returns a specific proxy by ID.

func (*Client) GetProxyList 

func (c *Client) GetProxyList(_ context.Context) []proxy.Proxy

GetProxyList returns all proxies for the authenticated user.

func (*Client) GetSettings 

func (c *Client) GetSettings(ctx context.Context) (*settings.Settings, error)

GetSettings retrieves the server settings.

func (*Client) GetStatusPage 

func (c *Client) GetStatusPage(ctx context.Context, slug string) (*statuspage.StatusPage, error)

GetStatusPage retrieves a specific status page by slug. Note: The server does not return PublicGroupList in this endpoint. PublicGroupList must be maintained separately when calling SaveStatusPage.

func (*Client) GetStatusPages 

func (c *Client) GetStatusPages(_ context.Context) (map[int64]statuspage.StatusPage, error)

GetStatusPages retrieves all status pages from the client cache.

func (*Client) GetTag 

func (c *Client) GetTag(ctx context.Context, tagID int64) (tag.Tag, error)

GetTag retrieves a specific tag by ID.

func (*Client) GetTagMonitors 

func (c *Client) GetTagMonitors(_ context.Context, tagID int64) ([]int64, error)

GetTagMonitors retrieves all monitor IDs associated with a specific tag. This method uses the client's local state cache, which is kept synchronized via socket.io events. The cache is automatically updated by monitorList, updateMonitorIntoList, and deleteMonitorFromList events.

func (*Client) GetTags 

func (c *Client) GetTags(ctx context.Context) ([]tag.Tag, error)

GetTags retrieves all tags.

func (*Client) PauseMaintenance 

func (c *Client) PauseMaintenance(ctx context.Context, id int64) error

PauseMaintenance pauses (deactivates) a maintenance window.

func (*Client) PauseMonitor 

func (c *Client) PauseMonitor(ctx context.Context, monitorID int64) error

PauseMonitor pauses a monitor by ID.

func (*Client) PostIncident 

func (c *Client) PostIncident(ctx context.Context, slug string, incident *statuspage.Incident) error

PostIncident posts or updates an incident on a status page.

func (*Client) ResumeMaintenance 

func (c *Client) ResumeMaintenance(ctx context.Context, id int64) error

ResumeMaintenance resumes (activates) a maintenance window.

func (*Client) ResumeMonitor 

func (c *Client) ResumeMonitor(ctx context.Context, monitorID int64) error

ResumeMonitor resumes a monitor by ID.

func (*Client) SaveStatusPage 

func (c *Client) SaveStatusPage(ctx context.Context, sp *statuspage.StatusPage) ([]statuspage.PublicGroup, error)

SaveStatusPage updates an existing status page configuration and returns the updated public group list with IDs.

func (*Client) SetMaintenanceStatusPage 

func (c *Client) SetMaintenanceStatusPage(ctx context.Context, maintenanceID int64, statusPageIDs []int64) error

SetMaintenanceStatusPage sets the status pages associated with a maintenance window. This replaces all existing status page associations.

func (*Client) SetMonitorMaintenance 

func (c *Client) SetMonitorMaintenance(ctx context.Context, maintenanceID int64, monitorIDs []int64) error

SetMonitorMaintenance sets the monitors associated with a maintenance window. This replaces all existing monitor associations.

func (*Client) SetSettings 

func (c *Client) SetSettings(ctx context.Context, s settings.Settings, password string) error

SetSettings updates the server settings.

func (*Client) TestDockerHost 

func (c *Client) TestDockerHost(ctx context.Context, config dockerhost.Config) (*dockerhost.TestResult, error)

TestDockerHost tests a Docker host connection without creating the host.

func (*Client) UnpinIncident 

func (c *Client) UnpinIncident(ctx context.Context, slug string) error

UnpinIncident unpins the currently pinned incident on a status page.

func (*Client) UpdateDockerHost 

func (c *Client) UpdateDockerHost(ctx context.Context, config dockerhost.Config) error

UpdateDockerHost updates an existing Docker host.

func (*Client) UpdateMaintenance 

func (c *Client) UpdateMaintenance(ctx context.Context, m *maintenance.Maintenance) error

UpdateMaintenance updates an existing maintenance window.

func (*Client) UpdateMonitor 

func (c *Client) UpdateMonitor(ctx context.Context, mon monitor.Monitor) error

UpdateMonitor updates an existing monitor.

func (*Client) UpdateMonitorTag 

func (c *Client) UpdateMonitorTag(ctx context.Context, tagID int64, monitorID int64, value string) error

UpdateMonitorTag updates the value of a monitor-tag association.

func (*Client) UpdateNotification 

func (c *Client) UpdateNotification(ctx context.Context, notif notification.Notification) error

UpdateNotification updates an existing notification.

func (*Client) UpdateProxy 

func (c *Client) UpdateProxy(ctx context.Context, config proxy.Config) error

UpdateProxy updates an existing proxy.

func (*Client) UpdateTag 

func (c *Client) UpdateTag(ctx context.Context, t tag.Tag) error

UpdateTag updates an existing tag.

type Option 

type Option func(c *Client)

Option is a functional option for configuring a Client.

func WithAutosetup 

func WithAutosetup() Option

WithAutosetup enables automatic server setup during client connection.

func WithConnectTimeout 

func WithConnectTimeout(timeout time.Duration) Option

WithConnectTimeout sets the socket.io client connection timeout. This timeout defines the overall duration, with is allowed for establishing the connection to Uptime Kuma. In the case of autosetup with an uninitialized Uptime Kuma this timeout also includes the time required for the initial setup.

func WithLogLevel 

func WithLogLevel(level int) Option

WithLogLevel sets the socket.io client logging level.

Source Files

View all Source files

Directories

Path Synopsis
internal
ptr
Package maintenance provides types and utilities for managing Uptime Kuma maintenance windows.
 Package maintenance provides types and utilities for managing Uptime Kuma maintenance windows.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.