PHPackages                             scherhak/uplinkr-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. [HTTP & Networking](/categories/http)
4. /
5. scherhak/uplinkr-api

ActiveLibrary[HTTP & Networking](/categories/http)

scherhak/uplinkr-api
====================

REST API package for Uplinkr monitoring.

v0.1.0(3mo ago)01MITPHPPHP ^8.4CI passing

Since Mar 22Pushed 3mo agoCompare

[ Source](https://github.com/scherhak/uplinkr-api)[ Packagist](https://packagist.org/packages/scherhak/uplinkr-api)[ Docs](https://uplinkr.dev)[ RSS](/packages/scherhak-uplinkr-api/feed)WikiDiscussions main Synced 3w ago

READMEChangelog (1)Dependencies (7)Versions (2)Used By (0)

 [![Uplinkr Logo](.github/uplinkr-api-mascot-150.png)](.github/uplinkr-api-mascot-150.png)

Uplinkr API
===========

[](#uplinkr-api)

 REST API for Uplinkr monitoring projects, probes, and global settings.
 Versioned Laravel endpoints for managing Uplinkr over HTTP.

 [ ![tests](https://github.com/scherhak/uplinkr-api/actions/workflows/tests.yml/badge.svg) ](https://github.com/scherhak/uplinkr-api/actions/workflows/tests.yml) [ ![Latest Stable Version](https://camo.githubusercontent.com/4be20b06449bd32d3ec714baf5d2d598e30d81915d322773e46a6f5ef6e2cc0b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736368657268616b2f75706c696e6b722d617069) ](https://packagist.org/packages/scherhak/uplinkr-api) [ ![Total Downloads](https://camo.githubusercontent.com/d098cfdad6a610cc88786d58e5046bce070cd3af0902c2893c92933639a10f32/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f736368657268616b2f75706c696e6b722d617069) ](https://packagist.org/packages/scherhak/uplinkr-api) [ ![License](https://camo.githubusercontent.com/849ffd44b27329e296c62f721cf63b394b0cc7c1dc08a476c49ab2a22ebb9728/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f736368657268616b2f75706c696e6b722d617069) ](https://packagist.org/packages/scherhak/uplinkr-api)

REST API for [Uplinkr](https://github.com/scherhak/uplinkr) monitoring projects, probes, and global settings.

Uplinkr API extends the CLI-first Uplinkr package with HTTP endpoints so monitoring data and configuration can be managed from external systems, internal tooling, or test clients such as Postman.

Documentation
-------------

[](#documentation)

- Homepage and docs:
- Package repository:
- Base package:

What is Uplinkr API?
--------------------

[](#what-is-uplinkr-api)

**Uplinkr API** is a lightweight Laravel package that exposes selected Uplinkr functionality through a versioned REST API.

It is designed for teams that want to:

- manage Uplinkr projects and probes over HTTP
- integrate monitoring setup into internal tools or deployment flows
- inspect and update global monitoring settings programmatically
- use OpenAPI-based API documentation during development

The package stays close to the architecture of the base package:

- file-based storage remains the source of truth
- API routes are explicit and versioned under `/api/v1`
- package logic prefers direct integration with handlers and storage classes
- no dashboard, no SPA, no additional persistence layer

Key Features
------------

[](#key-features)

- **REST API for Uplinkr** with versioned endpoints under `/api/v1`
- **Project management** for listing, creating, updating, and deleting projects
- **Probe management** with project-scoped probe resources
- **Global settings endpoint** for I-am-alive configuration
- **API key authentication** with optional Bearer token support
- **Rate limiting** for the API surface
- **Interactive API docs** via OpenAPI UI under `/api/docs`
- **Direct integration with Uplinkr internals** instead of shelling out to Artisan commands

How It Works
------------

[](#how-it-works)

Uplinkr API is installed into a Laravel application that already uses, or should use, Uplinkr.

The package registers:

1. versioned API routes
2. JSON controllers and actions
3. API-key based request protection
4. interactive OpenAPI documentation

The API delegates to the underlying Uplinkr package:

- project endpoints use Uplinkr project handlers
- probe endpoints use Uplinkr probe handlers
- settings endpoints use `Uplinkr\Storage\FileSettingsStorage`

This keeps the API predictable and avoids coupling HTTP behavior to CLI output.

Quick Start
-----------

[](#quick-start)

#### 1. Install the package

[](#1-install-the-package)

```
composer require scherhak/uplinkr-api
```

`scherhak/uplinkr` is installed as a dependency.

#### 2. Optionally publish the API config

[](#2-optionally-publish-the-api-config)

```
php artisan vendor:publish --tag=uplinkr-api-config
```

Publishing is optional. The package works without publishing because config values are merged automatically.

#### 3. Configure API access

[](#3-configure-api-access)

```
UPLINKR_API_AUTH_ENABLED=true
UPLINKR_API_AUTH_HEADER=X-Uplinkr-Api-Key
UPLINKR_API_KEYS=replace-me-with-a-long-random-key
UPLINKR_API_ACCEPT_BEARER_TOKEN=false

UPLINKR_API_RATE_LIMIT_ENABLED=true
UPLINKR_API_RATE_LIMIT_MAX_ATTEMPTS=60
UPLINKR_API_RATE_LIMIT_DECAY_MINUTES=1
```

#### 4. Clear config cache

[](#4-clear-config-cache)

```
php artisan optimize:clear
```

#### 5. Open the API docs

[](#5-open-the-api-docs)

- UI: `GET /api/docs`
- OpenAPI JSON: `GET /api/docs/openapi`

Authentication
--------------

[](#authentication)

By default, the API expects an API key in a custom header:

```
X-Uplinkr-Api-Key: replace-me-with-a-long-random-key
```

If Bearer support is enabled, the following is also accepted:

```
Authorization: Bearer replace-me-with-a-long-random-key
```

If authentication is enabled and the key is missing or invalid, the API responds with `401 Unauthorized`.

API Documentation
-----------------

[](#api-documentation)

The package uses [`dedoc/scramble`](https://github.com/dedoc/scramble) to provide interactive API documentation.

- UI: `GET /api/docs`
- OpenAPI JSON: `GET /api/docs/openapi`

Documentation is rendered dynamically from the registered package routes. No generate step is required.

Available Endpoints
-------------------

[](#available-endpoints)

### Projects

[](#projects)

MethodURI`GET``/api/v1/projects``POST``/api/v1/projects``GET``/api/v1/projects/{project}``PATCH``/api/v1/projects/{project}``DELETE``/api/v1/projects/{project}`### Probes

[](#probes)

MethodURI`GET``/api/v1/probes``POST``/api/v1/probes``GET``/api/v1/projects/{project}/probes``POST``/api/v1/projects/{project}/probes``GET``/api/v1/projects/{project}/probes/{probeId}``PATCH``/api/v1/projects/{project}/probes/{probeId}``DELETE``/api/v1/projects/{project}/probes/{probeId}`### Settings

[](#settings)

MethodURI`GET``/api/v1/settings/iam-alive``PATCH``/api/v1/settings/iam-alive`Example request body for `PATCH /api/v1/settings/iam-alive`:

```
{
  "enabled": true,
  "interval_hours": 6,
  "channels": ["mail", "webhook"]
}
```

Example Requests
----------------

[](#example-requests)

Create a project:

```
curl -X POST http://localhost/api/v1/projects \
  -H "X-Uplinkr-Api-Key: replace-me-with-a-long-random-key" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "status-page",
    "label": "Status Page",
    "description": "Public status page monitoring"
  }'
```

Create a project probe:

```
curl -X POST http://localhost/api/v1/projects/status-page/probes \
  -H "X-Uplinkr-Api-Key: replace-me-with-a-long-random-key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/health",
    "method": "GET",
    "latency": 1500
  }'
```

Read I-am-alive settings:

```
curl http://localhost/api/v1/settings/iam-alive \
  -H "X-Uplinkr-Api-Key: replace-me-with-a-long-random-key"
```

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

[](#configuration)

Default route prefix:

```
UPLINKR_API_ROUTE_PREFIX=api/v1
```

Main configuration areas:

- route prefix and route middleware
- API key authentication header and accepted keys
- optional Bearer token support
- rate limiting behavior

If you need to customize package defaults locally, publish the config first:

```
php artisan vendor:publish --tag=uplinkr-api-config
```

Design Decisions
----------------

[](#design-decisions)

- **Handlers over Commands**: The API uses Uplinkr handlers directly for projects and probes. This avoids shell execution, CLI output parsing, and unnecessary overhead.
- **Storage access for settings**: The settings API uses `Uplinkr\Storage\FileSettingsStorage` directly because the underlying resource is a single global settings document.
- **Versioned routing**: All package endpoints live under `/api/v1` to keep future evolution explicit.
- **Minimal scope**: The package intentionally exposes a focused subset of Uplinkr through HTTP instead of introducing a dashboard or separate application layer.

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

[](#requirements)

- **PHP:** 8.4 or higher
- **Laravel:** 12.x

Development Notes
-----------------

[](#development-notes)

- Postman collection: [postman\_collection.json](postman_collection.json)
- Package config: [config/uplinkr-api.php](config/uplinkr-api.php)
- Route definitions: [routes/api.php](routes/api.php)

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

[](#contributing)

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

Security
--------

[](#security)

If you discover a security issue, please see [SECURITY.md](SECURITY.md) for how to report it responsibly.

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE).

###  Health Score

34

—

LowBetter than 75% of packages

Maintenance82

Actively maintained with recent releases

Popularity1

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity41

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

93d ago

### Community

Maintainers

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

---

Top Contributors

[![scherhak](https://avatars.githubusercontent.com/u/4221861?v=4)](https://github.com/scherhak "scherhak (24 commits)")

---

Tags

apilaravelmonitoringreststatusuptimeprobe

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/scherhak-uplinkr-api/health.svg)

```
[![Health](https://phpackages.com/badges/scherhak-uplinkr-api/health.svg)](https://phpackages.com/packages/scherhak-uplinkr-api)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.1M337](/packages/psalm-plugin-laravel)[api-platform/laravel

API Platform support for Laravel

59156.3k11](/packages/api-platform-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76518.2M118](/packages/laravel-mcp)

PHPackages © 2026

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