PHPackages                             sinask/laravel-kuma-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. sinask/laravel-kuma-api

ActiveLibrary[API Development](/categories/api)

sinask/laravel-kuma-api
=======================

Laravel wrapper for the Uptime Kuma API

1.0.1(5mo ago)010MITPHPPHP ^8.2

Since Dec 8Pushed 5mo agoCompare

[ Source](https://github.com/sinask/laravel-kuma-api)[ Packagist](https://packagist.org/packages/sinask/laravel-kuma-api)[ RSS](/packages/sinask-laravel-kuma-api/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (3)Dependencies (4)Versions (4)Used By (0)

Laravel Uptime Kuma API
=======================

[](#laravel-uptime-kuma-api)

A comprehensive Laravel package for interacting with [Uptime Kuma](https://github.com/louislam/uptime-kuma) monitoring systems. This package provides a fluent, Laravel-friendly API client for managing monitors, notifications, status pages, maintenance windows, and more.

Features
--------

[](#features)

- Full CRUD operations for monitors, notifications, proxies, tags, and more
- Status page management with incident reporting
- Maintenance window scheduling
- Docker host integration
- API key management
- 2FA support
- Database backup and management
- Strongly-typed enums for monitor types, notification providers, etc.
- Data Transfer Objects (DTOs) for type-safe data handling
- Laravel Facade for convenient access
- Auto-authentication with configured credentials

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 10.x, 11.x, or 12.x
- Uptime Kuma 1.21+

Installation
------------

[](#installation)

Install the package via Composer:

```
composer require sinask/laravel-kuma-api
```

Configuration
-------------

[](#configuration)

Publish the configuration file:

```
php artisan vendor:publish --tag=uptime-kuma-config
```

Add your Uptime Kuma credentials to your `.env` file:

```
UPTIME_KUMA_URL=http://your-uptime-kuma-server:3001
UPTIME_KUMA_USERNAME=admin
UPTIME_KUMA_PASSWORD=your-password
UPTIME_KUMA_TOKEN=       # Optional: 2FA token if enabled
```

The configuration file (`config/uptime-kuma.php`):

```
return [
    'base_url' => env('UPTIME_KUMA_URL', 'http://127.0.0.1:3001'),
    'username' => env('UPTIME_KUMA_USERNAME'),
    'password' => env('UPTIME_KUMA_PASSWORD'),
    'two_factor_token' => env('UPTIME_KUMA_TOKEN'),
];
```

Basic Usage
-----------

[](#basic-usage)

### Using the Facade

[](#using-the-facade)

```
use UptimeKuma\LaravelApi\Facades\UptimeKuma;
use UptimeKuma\LaravelApi\Support\MonitorType;

// Get all monitors
$monitors = UptimeKuma::monitors();

// Get a specific monitor
$monitor = UptimeKuma::monitor(1);

// Create a new HTTP monitor
UptimeKuma::createMonitor([
    'name' => 'My Website',
    'type' => MonitorType::HTTP->value,
    'url' => 'https://example.com',
    'interval' => 60,
]);

// Pause/Resume a monitor
UptimeKuma::pauseMonitor(1);
UptimeKuma::resumeMonitor(1);

// Delete a monitor
UptimeKuma::deleteMonitor(1);
```

### Using Dependency Injection

[](#using-dependency-injection)

```
use UptimeKuma\LaravelApi\Http\UptimeKumaClient;

class MonitorController extends Controller
{
    public function __construct(
        private UptimeKumaClient $client
    ) {}

    public function index()
    {
        return $this->client->monitors();
    }
}
```

Monitor Types
-------------

[](#monitor-types)

The package includes all monitor types supported by Uptime Kuma:

```
use UptimeKuma\LaravelApi\Support\MonitorType;

MonitorType::HTTP;          // HTTP(s) monitoring
MonitorType::KEYWORD;       // HTTP(s) with keyword check
MonitorType::JSON_QUERY;    // HTTP(s) with JSON query
MonitorType::PING;          // Ping monitoring
MonitorType::PORT;          // TCP Port monitoring
MonitorType::DNS;           // DNS monitoring
MonitorType::PUSH;          // Push monitoring
MonitorType::DOCKER;        // Docker container monitoring
MonitorType::STEAM;         // Steam game server
MonitorType::GAMEDIG;       // Game server (GameDig)
MonitorType::MQTT;          // MQTT broker
MonitorType::POSTGRES;      // PostgreSQL
MonitorType::MYSQL;         // MySQL/MariaDB
MonitorType::MONGODB;       // MongoDB
MonitorType::SQLSERVER;     // Microsoft SQL Server
MonitorType::REDIS;         // Redis
MonitorType::RADIUS;        // RADIUS
MonitorType::GRPC_KEYWORD;  // gRPC with keyword
MonitorType::REAL_BROWSER;  // Real browser (Chrome/Chromium)
MonitorType::KAFKA_PRODUCER;// Kafka Producer
MonitorType::TAILSCALE_PING;// Tailscale Ping
MonitorType::GROUP;         // Monitor Group
```

Notifications
-------------

[](#notifications)

### Managing Notifications

[](#managing-notifications)

```
use UptimeKuma\LaravelApi\Support\NotificationType;

// Get all notifications
$notifications = UptimeKuma::notifications();

// Create a Discord notification
UptimeKuma::createNotification([
    'name' => 'Discord Alerts',
    'type' => NotificationType::DISCORD->value,
    'isDefault' => true,
    'discordWebhookUrl' => 'https://discord.com/api/webhooks/...',
]);

// Create a Slack notification
UptimeKuma::createNotification([
    'name' => 'Slack Alerts',
    'type' => NotificationType::SLACK->value,
    'slackwebhookURL' => 'https://hooks.slack.com/services/...',
]);

// Test a notification
UptimeKuma::testNotification([
    'type' => NotificationType::TELEGRAM->value,
    'telegramBotToken' => 'your-bot-token',
    'telegramChatID' => 'your-chat-id',
]);
```

### Supported Notification Providers (53+)

[](#supported-notification-providers-53)

Discord, Slack, Telegram, Email (SMTP), Teams, PagerDuty, OpsGenie, Pushover, Gotify, ntfy, Matrix, Mattermost, Rocket.Chat, Twilio, Webhook, and many more.

Status Pages
------------

[](#status-pages)

```
// Get all status pages
$pages = UptimeKuma::statusPages();

// Create a status page
UptimeKuma::createStatusPage('my-status', 'My Service Status');

// Update a status page
UptimeKuma::updateStatusPage('my-status', [
    'title' => 'Updated Title',
    'description' => 'Service status dashboard',
    'published' => true,
    'showTags' => true,
]);

// Post an incident
UptimeKuma::postIncident('my-status',
    'Service Degradation',
    'We are investigating reports of slow response times.',
    'warning'  // info, warning, danger, primary, light, dark
);

// Remove incident
UptimeKuma::unpinIncident('my-status');

// Delete status page
UptimeKuma::deleteStatusPage('my-status');
```

Maintenance Windows
-------------------

[](#maintenance-windows)

```
use UptimeKuma\LaravelApi\Support\MaintenanceStrategy;

// Get all maintenance windows
$maintenances = UptimeKuma::maintenances();

// Create a scheduled maintenance
UptimeKuma::createMaintenance([
    'title' => 'Weekly Maintenance',
    'description' => 'Regular system maintenance',
    'strategy' => MaintenanceStrategy::RECURRING_WEEKDAY->value,
    'active' => true,
    'weekdays' => [0], // Sunday
    'timeRange' => ['02:00', '04:00'],
]);

// Pause/Resume maintenance
UptimeKuma::pauseMaintenance(1);
UptimeKuma::resumeMaintenance(1);
```

Tags
----

[](#tags)

```
// Get all tags
$tags = UptimeKuma::tags();

// Create a tag
UptimeKuma::createTag('Production', '#ff0000');

// Add tag to a monitor
UptimeKuma::addMonitorTag(
    tagId: 1,
    monitorId: 5,
    value: 'optional-value'
);

// Remove tag from monitor
UptimeKuma::deleteMonitorTag(1, 5);
```

Proxies
-------

[](#proxies)

```
use UptimeKuma\LaravelApi\Support\ProxyProtocol;

// Get all proxies
$proxies = UptimeKuma::proxies();

// Create a proxy
UptimeKuma::createProxy([
    'protocol' => ProxyProtocol::SOCKS5->value,
    'host' => 'proxy.example.com',
    'port' => 1080,
    'auth' => true,
    'username' => 'user',
    'password' => 'pass',
    'active' => true,
]);
```

Docker Hosts
------------

[](#docker-hosts)

```
use UptimeKuma\LaravelApi\Support\DockerType;

// Get Docker hosts
$hosts = UptimeKuma::dockerHosts();

// Add a Docker host
UptimeKuma::createDockerHost([
    'name' => 'Local Docker',
    'dockerType' => DockerType::SOCKET->value,
    'dockerDaemon' => '/var/run/docker.sock',
]);

// Test connection
UptimeKuma::testDockerHost([
    'dockerType' => DockerType::TCP->value,
    'dockerDaemon' => 'tcp://192.168.1.100:2375',
]);
```

Metrics & Heartbeats
------------------------

[](#metrics--heartbeats)

```
// Get heartbeats for a monitor
$heartbeats = UptimeKuma::heartbeats(monitorId: 1, hours: 24);

// Get important heartbeats (status changes)
$important = UptimeKuma::importantHeartbeats(1);

// Get average ping times
$avgPing = UptimeKuma::avgPing();

// Get uptime statistics
$uptime = UptimeKuma::uptime();

// Get SSL certificate info
$certInfo = UptimeKuma::certInfo();
```

Push Monitors
-------------

[](#push-monitors)

For push-type monitors, you can send heartbeats from your application:

```
// Send a successful heartbeat
UptimeKuma::sendHeartbeat(
    pushToken: 'your-push-token',
    status: 'up',
    msg: 'OK',
    ping: 50
);

// Send a failure heartbeat
UptimeKuma::sendHeartbeat(
    pushToken: 'your-push-token',
    status: 'down',
    msg: 'Database connection failed'
);
```

API Keys
--------

[](#api-keys)

```
// Get all API keys
$apiKeys = UptimeKuma::apiKeys();

// Create an API key
$key = UptimeKuma::createApiKey(
    name: 'CI/CD Integration',
    expires: '2025-12-31',
    active: true
);

// Delete an API key
UptimeKuma::deleteApiKey(1);
```

Settings & Database
-----------------------

[](#settings--database)

```
// Get settings
$settings = UptimeKuma::settings();

// Update settings
UptimeKuma::updateSettings([
    'primaryBaseURL' => 'https://status.example.com',
]);

// Change password
UptimeKuma::changePassword('current-password', 'new-password');

// Database operations
$size = UptimeKuma::databaseSize();
UptimeKuma::shrinkDatabase();

// Backup
$backup = UptimeKuma::exportBackup();
UptimeKuma::importBackup($backupData);

// Clear data
UptimeKuma::clearEvents();
UptimeKuma::clearStatistics();
```

Two-Factor Authentication
-------------------------

[](#two-factor-authentication)

```
// Check 2FA status
$status = UptimeKuma::status2FA();

// Setup 2FA
$setup = UptimeKuma::prepare2FA('your-password');
// Returns QR code and secret

// Verify token
UptimeKuma::verify2FA('123456');

// Enable 2FA
UptimeKuma::save2FA('your-password');

// Disable 2FA
UptimeKuma::disable2FA('your-password');
```

Data Transfer Objects
---------------------

[](#data-transfer-objects)

The package includes DTOs for type-safe data handling:

```
use UptimeKuma\LaravelApi\Data\Monitor;
use UptimeKuma\LaravelApi\Data\Notification;
use UptimeKuma\LaravelApi\Data\Heartbeat;
use UptimeKuma\LaravelApi\Data\StatusPage;
use UptimeKuma\LaravelApi\Data\Maintenance;
use UptimeKuma\LaravelApi\Data\Tag;
use UptimeKuma\LaravelApi\Data\Proxy;
use UptimeKuma\LaravelApi\Data\DockerHost;
use UptimeKuma\LaravelApi\Data\ApiKey;

// Create from API response
$monitor = Monitor::fromArray($response);
echo $monitor->name;
echo $monitor->type->value;

// Convert to array
$data = $monitor->toArray();
```

Error Handling
--------------

[](#error-handling)

```
use UptimeKuma\LaravelApi\Exceptions\UptimeKumaException;
use UptimeKuma\LaravelApi\Exceptions\AuthenticationException;

try {
    $monitors = UptimeKuma::monitors();
} catch (AuthenticationException $e) {
    // Handle authentication errors
    Log::error('Authentication failed: ' . $e->getMessage());
} catch (UptimeKumaException $e) {
    // Handle other API errors
    Log::error('API error: ' . $e->getMessage());
}
```

Using a Different Token
-----------------------

[](#using-a-different-token)

```
// Create a client with a specific token
$client = UptimeKuma::usingToken('your-api-token');
$monitors = $client->monitors();
```

Testing
-------

[](#testing)

Run the test suite:

```
composer test
```

The test suite uses mocked HTTP responses and does not require a running Uptime Kuma instance.

Contributing
------------

[](#contributing)

Contributions are welcome! Please feel free to submit a Pull Request.

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](LICENSE).

Credits
-------

[](#credits)

- This package is inspired by [uptime-kuma-api](https://github.com/lucasheld/uptime-kuma-api) Python library
- [Uptime Kuma](https://github.com/louislam/uptime-kuma) - The amazing self-hosted monitoring tool

###  Health Score

38

—

LowBetter than 84% of packages

Maintenance78

Regular maintenance activity

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 66.7% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

2

Last Release

152d ago

PHP version history (2 changes)1.0.0PHP ^8.1

1.0.1PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/a09c664554d9289e0fc3289787b20bfc0ae26c4d1521f61d5704d92ee8f82837?d=identicon)[sinask](/maintainers/sinask)

---

Top Contributors

[![sinask](https://avatars.githubusercontent.com/u/8592315?v=4)](https://github.com/sinask "sinask (4 commits)")[![claude](https://avatars.githubusercontent.com/u/81847?v=4)](https://github.com/claude "claude (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/sinask-laravel-kuma-api/health.svg)

```
[![Health](https://phpackages.com/badges/sinask-laravel-kuma-api/health.svg)](https://phpackages.com/packages/sinask-laravel-kuma-api)
```

###  Alternatives

[skagarwal/google-places-api

Google Places Api

1913.0M8](/packages/skagarwal-google-places-api)[dcblogdev/laravel-microsoft-graph

A Laravel Microsoft Graph API (Office365) package

168285.5k1](/packages/dcblogdev-laravel-microsoft-graph)[vluzrmos/slack-api

Wrapper for Slack.com WEB API.

102589.1k3](/packages/vluzrmos-slack-api)[smodav/mpesa

M-Pesa API implementation

16363.7k1](/packages/smodav-mpesa)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1344.8k1](/packages/jasara-php-amzn-selling-partner-api)[grantholle/powerschool-api

A Laravel package to make interacting with PowerSchool less painful.

1715.6k1](/packages/grantholle-powerschool-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)