- A card on the incident page, and GET /api/incidents/:id/before and /api/v1/incidents/:id/before: what the app knows happened in the 30 min to 24 h before an alert began (audit log, maintenance windows, update runs and patch plans, other alerts, a step in the server's own figures), scored by how related, what kind and how close - A host going down is shown once; Likely, Possible and Background; at most ten - Docs and roles updated Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
406 lines
23 KiB
Markdown
406 lines
23 KiB
Markdown
# API
|
||
|
||
Homelab Manager has two kinds of programmatic interface:
|
||
|
||
| Interface | For | Who can use it | Section |
|
||
|---|---|---|---|
|
||
| **The read API** — `/api/v1` | Scripts, Home Assistant, dashboards that want JSON about servers, alerts, incidents, inventory, network equipment, endpoint checks and maintenance | Anyone signed in can make a personal, read-only token | [The read API](#the-read-api) |
|
||
| **Machine addresses** — agent reports, heartbeats, `/metrics`, share links | The agents, cron jobs, Prometheus, status pages and calendars | Each has its own token | [Other addresses for machines](#other-addresses-for-machines) |
|
||
|
||
**There is no API that changes anything.** The read API refuses every verb but `GET` and `HEAD`. Everything else the app does (acknowledge an alert, start maintenance, add a check, change a setting)
|
||
is done in the web interface, which is not a supported API: its addresses and shapes change with the pages. The read API's shapes are a deliberate, stable contract.
|
||
|
||
Examples below use `https://hm.example.lan` for your `APP_BASE_URL`. Related pages: [PROMETHEUS-GRAFANA.md](PROMETHEUS-GRAFANA.md) for `/metrics`, [WEBHOOKS.md](WEBHOOKS.md) for being *told* when something
|
||
happens instead of asking, [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md), [MONITORING.md](MONITORING.md) for what the alert fields mean.
|
||
|
||
## The read API
|
||
|
||
### Getting a token
|
||
|
||
1. Sign in, open the **user menu → API tokens**. This is open to everyone signed in, whatever their role.
|
||
2. Give the token a name (e.g. `Home Assistant`) and choose how long it lasts: **30, 90 or 365 days, or until removed**.
|
||
3. Copy the token (it starts with `hlm_p_`). **It is shown once**; only its SHA-256 is kept.
|
||
|
||
A token belongs to the person who made it. They see and remove their own, nobody else's. A person can have **ten**. A token **stops working at once** when it is removed, when it expires and when
|
||
its owner is removed. It sees what its owner sees on the pages: no secrets, no passwords, no server tokens, no settings.
|
||
|
||
### Making a request
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer hlm_p_xxxxxxxxxxxxxxxxxxxxxxxx" https://hm.example.lan/api/v1/alerts
|
||
```
|
||
|
||
- The token goes in the **`Authorization: Bearer …` header only**. A token in the address (`?token=…`) is **not accepted**, because addresses end up in logs.
|
||
- **No token, a wrong one, an expired one and a removed one all get the same answer**: `401` with a JSON body and `WWW-Authenticate: Bearer realm="homelab-manager"`.
|
||
- **Only `GET` and `HEAD`.** Any other verb gets `405` (`{"error":"read_only"}`) with `Allow: GET, HEAD` — with a token or without.
|
||
- **Limits:** 300 requests a minute from one address (`429` beyond that). Answers carry `Cache-Control: no-store`.
|
||
- **Be gentle:** the data changes at the pace of the agents (every 15 minutes or so) and the checks (minutes). Polling more often than once a minute gains nothing.
|
||
|
||
### Conventions
|
||
|
||
- Times are **ISO 8601 in UTC** (`2026-10-20T21:44:30.244Z`). A few older fields written by the database itself (`createdAt` on a server) are `YYYY-MM-DD HH:MM:SS` in UTC.
|
||
- Sizes are **bytes**. Percentages are **0–100** (not 0–1).
|
||
- `url` is a **full address** into the app, built from `APP_BASE_URL`, so a script does not need to know where the app lives.
|
||
- Missing information is `null`, never an invented value. A server whose agent has never said which OS it runs has `operatingSystem: null`.
|
||
- Errors are JSON: `{ "error": "<code>", "message": "…" }` with `error` one of `unauthorized`, `read_only`, `not_found`, `invalid_id`.
|
||
- Unknown addresses under `/api/v1` get `404` and point at `GET /api/v1`.
|
||
|
||
### Addresses
|
||
|
||
| Address | What it answers |
|
||
|---|---|
|
||
| `GET /api/v1` | The list of these addresses. |
|
||
| `GET /api/v1/me` | Whose token this is. |
|
||
| `GET /api/v1/servers` | Every server. Filter with `?tag=` and `?status=online\|offline\|unknown`. |
|
||
| `GET /api/v1/servers/:id` | One server, the same shape. |
|
||
| `GET /api/v1/servers/:id/metrics?days=` | Its load, memory and disks over time. `days` 1–365 (7 by default). |
|
||
| `GET /api/v1/alerts` | What is wrong now. Filter with `?severity=`, `?category=`, `?acknowledged=true\|false`, `?silenced=true\|false`. |
|
||
| `GET /api/v1/incidents` | The record of alerts that began and ended. `?status=open\|resolved`, `?limit=` (1–500, default 100). |
|
||
| `GET /api/v1/incidents/:id` | One incident with its timeline. |
|
||
| `GET /api/v1/incidents/:id/before?minutes=` | What changed before it began, ranked by how likely each is to be connected. `minutes` 15–1440 (120 by default). |
|
||
| `GET /api/v1/inventory` | The hardware inventory. |
|
||
| `GET /api/v1/network` | Network equipment read from UniFi: devices, networks, Wi-Fi names, and which server is plugged into which device. |
|
||
| `GET /api/v1/endpoints` | The endpoint checks and how they are doing. |
|
||
| `GET /api/v1/endpoints/:id/history?days=` | One check's availability and answer times over time. |
|
||
| `GET /api/v1/maintenance` | Maintenance windows running now and coming up. |
|
||
|
||
### `GET /api/v1/me`
|
||
|
||
```json
|
||
{
|
||
"user": { "id": 1, "name": "Demo Admin", "email": "demo@example.lan", "role": "admin" },
|
||
"token": { "id": 1, "label": "Home Assistant", "expiresAt": "2027-01-18T21:45:43.390Z" }
|
||
}
|
||
```
|
||
|
||
`expiresAt` is `null` for a token with no end. A quick way to check a token works.
|
||
|
||
### `GET /api/v1/servers`
|
||
|
||
```json
|
||
{ "servers": [
|
||
{
|
||
"id": 1,
|
||
"name": "wiki-host",
|
||
"hostname": "wiki-host.lan",
|
||
"description": null,
|
||
"os": "linux",
|
||
"tags": ["prod"],
|
||
"ipAddresses": ["192.168.1.20"],
|
||
"status": "online",
|
||
"lastSeenAt": "2026-10-20T21:44:30.244Z",
|
||
"createdAt": "2026-01-01 00:00:00",
|
||
"agentVersion": 7,
|
||
"runsOnServerId": null,
|
||
"hardware": { "manufacturer": null, "model": null, "serial": null },
|
||
"operatingSystem": {
|
||
"id": "ubuntu", "name": "Ubuntu 24.04 LTS", "version": "24.04", "product": "Ubuntu 24.04 LTS",
|
||
"endsOn": "2029-05-31", "state": "ok", "daysLeft": 951
|
||
},
|
||
"cpu": { "model": "Intel(R) N100", "cores": 4, "loadPercent": 12.4 },
|
||
"memory": { "totalBytes": 16623411200, "usedBytes": 4210356224 },
|
||
"disks": [ { "mount": "/", "sizeBytes": 245107195904, "usedBytes": 61276798976, "usedPercent": 25 } ],
|
||
"updates": { "manager": "apt", "count": 5, "security": 2, "rebootRequired": false, "reportedAt": "2026-10-20T21:44:30.000Z" },
|
||
"health": { "failedUnits": 0, "reportedAt": "2026-10-20T21:44:30.000Z" },
|
||
"thresholds": null,
|
||
"url": "https://hm.example.lan/servers/1"
|
||
}
|
||
] }
|
||
```
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| `status` | `online` while the agent has reported within the offline limit (60 minutes unless the server has its own), `offline` after, `unknown` if it never has. |
|
||
| `lastSeenAt` | When the agent last reported. |
|
||
| `agentVersion` | The version of the agent script, as it says; `null` until it has said. |
|
||
| `runsOnServerId` | The server this one runs on (a VM's Proxmox host, say), when one is set. |
|
||
| `operatingSystem` | What the agent says it runs, and when that release stops being supported. `state` is `ok`, `soon` (inside the warning window), `ended` or `unknown` (a release the app has no date for); `daysLeft` is negative once it has ended. `null` until the agent has said. |
|
||
| `cpu.loadPercent` | Load average as a share of the cores — an approximation, not instantaneous usage. |
|
||
| `disks[].usedPercent` | One decimal. |
|
||
| `updates` | What is waiting to be installed; `null` when the agent does not report it. `security` is `null` when the package manager cannot say. |
|
||
| `health.failedUnits` | The number of failed services (Linux), when the agent reports them. |
|
||
| `thresholds` | The server's own alert limits, if it has any that replace the global ones; otherwise `null`. |
|
||
|
||
### `GET /api/v1/servers/:id/metrics?days=`
|
||
|
||
```json
|
||
{ "days": 7, "series": [
|
||
{ "metric": "cpu", "kind": "cpu", "label": "CPU load", "latest": 12.4, "trend": null,
|
||
"points": [ { "t": "2026-10-20T20:59:30.572Z", "v": 12 }, { "t": "2026-10-20T21:14:30.572Z", "v": 13.5 } ] },
|
||
{ "metric": "disk:/", "kind": "disk", "label": "Disk /", "latest": 25,
|
||
"trend": { "perDay": 0.4, "fit": 0.97, "spanDays": 13.9, "daysToFull": 188 },
|
||
"points": [ … ] }
|
||
] }
|
||
```
|
||
|
||
- `kind` is `cpu`, `mem` or `disk`; a disk's `metric` is `disk:<mount>`. Values are percentages.
|
||
- The range decides how fine the points are: up to **35 days** they are the samples themselves (one every 10–15 minutes, thinned to at most about 100 points); beyond that they are **hourly (to 120 days) or daily
|
||
averages** and carry `lo` and `hi` (the lowest and highest in that hour or day).
|
||
- A disk's `trend` is a straight-line fit: `perDay` is points per day, `fit` is how straight (0–1), `daysToFull` is set only when the disk is rising steadily. `null` for CPU and memory, and for a disk
|
||
with too little history.
|
||
|
||
### `GET /api/v1/alerts`
|
||
|
||
```json
|
||
{
|
||
"generatedAt": "2026-10-20T21:45:53.522Z",
|
||
"needingAttention": { "critical": 1, "warning": 3, "acknowledged": 0 },
|
||
"counts": { "critical": 1, "warning": 3, "info": 0, "silenced": 0, "grouped": 0 },
|
||
"couldntCheck": [
|
||
{ "name": "Proxmox “Lab PVE”", "error": "connect ECONNREFUSED 127.0.0.1:3071", "affects": ["Proxmox backups", "Server and storage health"] }
|
||
],
|
||
"alerts": [
|
||
{
|
||
"id": "monitoring:rule:1:server:1",
|
||
"severity": "critical",
|
||
"category": "monitoring",
|
||
"source": "Server",
|
||
"message": "wiki-host: cpu load is 95%, above 90% for 30 min [CPU above 90% for 30 minutes]",
|
||
"url": "https://hm.example.lan/servers/1?view=history",
|
||
"silenced": false,
|
||
"snoozedUntil": null,
|
||
"flapping": false,
|
||
"target": { "type": "server", "id": 1, "name": "wiki-host" },
|
||
"causedBy": null,
|
||
"affects": [],
|
||
"acknowledgement": null
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| `needingAttention` | What wants a look: critical and warning alerts that are not silenced and that nobody has acknowledged, and how many somebody has. This is the number on the menu badge. |
|
||
| `counts` | Everything active by severity, whether acknowledged or not. `silenced` are held back by maintenance (or snoozed); `grouped` are folded under the host that explains them. Neither is in `critical`/`warning`/`info`. |
|
||
| `couldntCheck` | Sources the app could not read this time, and which checks that leaves blind. **An empty `alerts` list with something here is not "all clear".** |
|
||
| `id` | Stable for the same problem: `<category>:<key>`. |
|
||
| `severity` | `critical`, `warning` or `info`. |
|
||
| `category` | `offline`, `disk`, `services`, `backup`, `updates`, `expiry`, `automation`, `integration`, `monitoring` or `tickets`. |
|
||
| `source` | Where it comes from: `Server`, `Proxmox`, `Synology`, `UniFi`, `Endpoint`, `Heartbeat` … |
|
||
| `silenced` | Under a maintenance window, snoozed, or folded under a host that is down. Notifications for it are held back. |
|
||
| `snoozedUntil` | When a snooze on it ends; `null` otherwise. |
|
||
| `flapping` | It keeps being raised and cleared; its messages are being held back. |
|
||
| `target` | What a maintenance window would silence it with (`server`, `integration`, `dns_provider` or `device`), or `null`. |
|
||
| `causedBy` | The alert it is folded under, as `{ name, alertId? }`, or `null`. |
|
||
| `affects` | On a host's alert: the servers on it whose own alerts are folded under this one. |
|
||
| `acknowledgement` | `{ by, at, note, until, assignee }` while someone has said they are on it; otherwise `null`. |
|
||
|
||
### `GET /api/v1/incidents` and `/:id`
|
||
|
||
An *incident* is one time an alert was raised and later went away; the same alert coming back is a new incident.
|
||
|
||
```json
|
||
{ "incidents": [
|
||
{ "id": 4, "alertKey": "updates:os-support:1", "severity": "warning", "peakSeverity": "warning", "category": "updates",
|
||
"source": "Server", "message": "wiki-host runs Ubuntu 18.04 LTS, whose support ended on 2023-05-31 …",
|
||
"link": "/servers/1", "target": { "type": "server", "id": 1, "name": "wiki-host" }, "causedBy": null,
|
||
"openedAt": "2026-10-20T21:45:53.522Z", "resolvedAt": null, "durationMs": 127, "open": true, "notes": 0 }
|
||
] }
|
||
```
|
||
|
||
`GET /api/v1/incidents/:id` adds the **timeline** (when it was raised, acknowledged, handed over, what was done to the thing it is about in the hour around it, when it resolved) and the notes
|
||
people wrote. Open incidents are always listed; resolved ones newest first, up to `limit`.
|
||
|
||
### `GET /api/v1/incidents/:id/before`
|
||
|
||
The "what changed before this?" list for one incident: what the app knows happened in the window before it began — settings and other changes in the audit log, maintenance windows that began or ended, update runs
|
||
and patch plans, other alerts raised first, and a step in the server's own figures — each scored and the best first.
|
||
|
||
```json
|
||
{ "incidentId": 1, "openedAt": "2026-10-21T20:08:08.000Z", "windowMinutes": 120,
|
||
"from": "2026-10-21T18:08:08.000Z", "to": "2026-10-21T20:09:08.000Z",
|
||
"suspects": [
|
||
{ "at": "2026-10-21T20:02:08.000Z", "minutesBefore": 6, "kind": "maintenance", "title": "Maintenance on pve1 ended", "detail": "Kernel update", "actor": "Olga",
|
||
"relation": "needs", "about": "pve1 — which it needs", "why": "About something it needs directly, 6 min before",
|
||
"score": 86, "confidence": "likely", "link": "/maintenance" }
|
||
],
|
||
"looked": { "auditEntries": 5, "maintenanceWindows": 1, "updateRuns": 1, "otherAlerts": 2, "series": 1 } }
|
||
```
|
||
|
||
| Field | Meaning |
|
||
|---|---|
|
||
| `kind` | `maintenance`, `update`, `alert` (another alert, or a host going down), `change`, `settings`, `metric` (a step in the server's own load, memory or disk) or `rule` (one of your alert rules was changed). |
|
||
| `relation` | How it is related to what the incident is about: `same`, `needs` (the host it runs on, the switch it is plugged into, something it depends on), `needed_by`, `everything` (a setting, DNS) or `other`. |
|
||
| `score`, `confidence` | 0–100, from how related it is, what kind of thing it is and how close in time. `likely` is 55 and over, `possible` 25 and over, otherwise `background`. Anything under 8 is left out. |
|
||
| `minutesBefore` | How long before the incident began. |
|
||
| `link` | A page in the app, as a path (not a full address). |
|
||
| `looked` | How much was looked through, so an empty `suspects` can say what it covered. An empty list means *nothing the app knows about*, not *nothing happened* — a change made on the machine itself is invisible to it. |
|
||
|
||
At most ten suspects are returned. It is a list of suspects, not a diagnosis.
|
||
|
||
### `GET /api/v1/inventory`
|
||
|
||
```json
|
||
{ "assets": [
|
||
{ "id": 3, "name": "NAS", "kind": "server", "manufacturer": "Synology", "model": "DS923+", "serial": "…", "location": "Rack A", "rackUnit": "U6-9",
|
||
"purchaseDate": "2024-03-02", "purchasePrice": 6500, "warrantyUntil": "2027-03-02", "endOfSupport": null, "replacementCost": 7200,
|
||
"powerWatts": 120, "notes": null, "server": { "id": 6, "name": "nas" }, "updatedAt": "2026-10-20T21:45:30.244Z" }
|
||
] }
|
||
```
|
||
|
||
`server` links a piece of hardware to the server it is, when it is one. `kind` is `server`, `storage`, `network`, `power`, `client` or `other`.
|
||
|
||
### `GET /api/v1/network`
|
||
|
||
Present once a UniFi integration has been read: `{ devices, networks, ssids, serverLinks }` — each device with its `state` (`online`, `offline`, `updating`, `pending`, `other`), `ip`, `mac`, `uptimeSeconds`,
|
||
firmware, what it is connected through and what depends on it; the networks (VLAN, address range); the Wi-Fi names (security, which network); and `serverLinks` saying which server is plugged into which
|
||
device (and port). Wi-Fi passphrases are never read, so they are never here.
|
||
|
||
### `GET /api/v1/endpoints` and `/:id/history`
|
||
|
||
```json
|
||
{ "endpoints": [
|
||
{ "id": 1, "name": "Wiki", "kind": "http", "target": "https://192.168.1.20/", "port": null, "enabled": true,
|
||
"status": "up", "lastCheckedAt": "2026-10-20T21:50:00.000Z", "lastResponseMs": 41, "lastMessage": null,
|
||
"certificateExpiresAt": "2027-01-04T12:00:00.000Z", "uptime24hPercent": 100, "uptime7dPercent": 99.9,
|
||
"averageResponseMs24h": 44, "serverId": 1 }
|
||
] }
|
||
```
|
||
|
||
`status` is `up`, `down`, `unknown` (never asked yet) or `paused` (switched off). `lastMessage` is set only while it is failing (why). `kind` is `http`, `tcp` or `tls`.
|
||
|
||
`/:id/history?days=` answers `{ check: {id, name}, … points … }`: the availability and answer times over 1–365 days, drawn from each answer (up to 2 days), the hourly figures (up to 120 days) or the daily
|
||
ones, whichever is fine enough and still kept.
|
||
|
||
### `GET /api/v1/maintenance`
|
||
|
||
```json
|
||
{ "active": [
|
||
{ "id": 1, "target": { "type": "server", "id": 3, "name": "photos", "kind": "Server" }, "reason": "Kernel update",
|
||
"startsAt": "2026-10-20T21:45:43.616Z", "endsAt": "2026-10-20T22:45:43.616Z", "createdBy": "Demo Admin" } ],
|
||
"upcoming": [] }
|
||
```
|
||
|
||
### Examples
|
||
|
||
**curl and `jq`: is anything critical?**
|
||
|
||
```bash
|
||
curl -fsS -H "Authorization: Bearer $HLM_TOKEN" https://hm.example.lan/api/v1/alerts \
|
||
| jq -r '.alerts[] | select(.severity=="critical" and (.silenced|not)) | "\(.source): \(.message)"'
|
||
```
|
||
|
||
**A shell check that fails when something needs attention** (for cron, or a Kuma "push" monitor):
|
||
|
||
```bash
|
||
n=$(curl -fsS -H "Authorization: Bearer $HLM_TOKEN" https://hm.example.lan/api/v1/alerts | jq '.needingAttention.critical')
|
||
[ "$n" -eq 0 ] || { echo "$n critical alerts"; exit 1; }
|
||
```
|
||
|
||
**Python:**
|
||
|
||
```python
|
||
import os, requests
|
||
|
||
BASE = "https://hm.example.lan/api/v1"
|
||
HEADERS = {"Authorization": f"Bearer {os.environ['HLM_TOKEN']}"}
|
||
|
||
def get(path, **params):
|
||
r = requests.get(f"{BASE}{path}", headers=HEADERS, params=params, timeout=10)
|
||
r.raise_for_status()
|
||
return r.json()
|
||
|
||
for s in get("/servers", status="offline")["servers"]:
|
||
print(s["name"], "last seen", s["lastSeenAt"])
|
||
|
||
full = [(s["name"], d["mount"], d["usedPercent"]) for s in get("/servers")["servers"] for d in s["disks"] if d["usedPercent"] and d["usedPercent"] > 85]
|
||
print(full)
|
||
```
|
||
|
||
**Node.js (18+):**
|
||
|
||
```js
|
||
const res = await fetch("https://hm.example.lan/api/v1/endpoints", { headers: { Authorization: `Bearer ${process.env.HLM_TOKEN}` } });
|
||
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
|
||
const { endpoints } = await res.json();
|
||
console.log(endpoints.filter((e) => e.status === "down").map((e) => e.name));
|
||
```
|
||
|
||
**Home Assistant** — put the whole header value, including the word `Bearer`, in `secrets.yaml`:
|
||
|
||
```yaml
|
||
# secrets.yaml
|
||
hlm_auth: "Bearer hlm_p_xxxxxxxxxxxxxxxxxxxxxxxx"
|
||
```
|
||
|
||
```yaml
|
||
# configuration.yaml
|
||
rest:
|
||
- resource: https://hm.example.lan/api/v1/alerts
|
||
scan_interval: 60
|
||
headers:
|
||
Authorization: !secret hlm_auth
|
||
sensor:
|
||
- name: "Homelab critical alerts"
|
||
value_template: "{{ value_json.needingAttention.critical }}"
|
||
- name: "Homelab warnings"
|
||
value_template: "{{ value_json.needingAttention.warning }}"
|
||
binary_sensor:
|
||
- name: "Homelab needs attention"
|
||
value_template: "{{ value_json.needingAttention.critical > 0 }}"
|
||
device_class: problem
|
||
```
|
||
|
||
A similar sensor on `/api/v1/servers?status=offline` with `value_template: "{{ value_json.servers | length }}"` counts servers that have gone quiet.
|
||
|
||
## Other addresses for machines
|
||
|
||
These do not use a session and are not part of the read API. Each is protected by its own token and does one thing.
|
||
|
||
### Agent report — `POST /api/agent/report`
|
||
|
||
What the agents on the servers call, every 15 minutes by default. The token is the **server's own** (shown once when the server is added under **Servers → Add a server**, and put in the agent by the install
|
||
one-liner); it can only replace *that* server's report. You can call it yourself from anything that can make an HTTPS request — a router, a NAS, a script — to make a server appear and be monitored.
|
||
|
||
```bash
|
||
curl -fsS -X POST https://hm.example.lan/api/agent/report \
|
||
-H "Authorization: Bearer <the server's token>" -H "Content-Type: application/json" \
|
||
-d '{
|
||
"hostname": "nas",
|
||
"os_type": "linux",
|
||
"agent_version": 7,
|
||
"reported_at": "2026-10-20T21:50:00Z",
|
||
"system": {
|
||
"ip_addresses": ["192.168.1.30"],
|
||
"cpu": { "model": "Intel(R) N100", "cores": 4, "load_percent": 12.4 },
|
||
"memory": { "total_bytes": 16623411200, "used_bytes": 4210356224 },
|
||
"disks": [ { "mount": "/", "size_bytes": 245107195904, "used_bytes": 61276798976 } ],
|
||
"listening_ports": [ { "protocol": "tcp", "port": 22, "address": "0.0.0.0", "process": "sshd" } ],
|
||
"updates": { "manager": "apt", "count": 5, "security": 2, "reboot_required": false },
|
||
"health": {
|
||
"failed_units": [ { "unit": "foo.service", "description": "Foo" } ],
|
||
"smart": [ { "device": "/dev/sda", "model": "WD Red", "healthy": true, "temperature_c": 38, "wear_percent": null } ],
|
||
"zfs": [ { "name": "tank", "health": "ONLINE", "capacity_percent": 61 } ]
|
||
},
|
||
"hardware": { "manufacturer": "ASUS", "model": "PN42", "serial": "…" },
|
||
"os": { "id": "debian", "name": "Debian GNU/Linux 12", "version": "12" }
|
||
},
|
||
"tasks": [ { "schedule_type": "cron", "name": "backup", "command": "/usr/local/bin/backup.sh", "schedule_expression": "0 3 * * *", "source": "root" } ]
|
||
}'
|
||
```
|
||
|
||
- **Everything in `system` is optional**, and a part that is malformed is dropped rather than costing the report. Text is trimmed to a sane length. `tasks` may be `[]` (but is required).
|
||
- Answers: `202` with `{ "ok": true, "taskCount": 1 }` when the report is taken; `401` for no or a wrong token (`missing_token`, `invalid_token`); `400` (`invalid_body`) for a report that is not JSON of this shape. Reports may be up to **4 MB**.
|
||
- `schedule_type` is `cron`, `systemd_timer` or `windows_task`. `os_type` is recorded only if it is `linux` or `windows`. The same token replaces the previous report's tasks and figures.
|
||
- `GET /api/agent/report/update?version=<n>` (same token) answers `{ "update": bool, "version": …, "sha256": … }` for an agent that has been told to keep itself up to date; see [AGENT_UPDATE.md](../AGENT_UPDATE.md).
|
||
|
||
How the figures are used is in [MONITORING.md](MONITORING.md).
|
||
|
||
### Heartbeats, metrics, status pages and calendars
|
||
|
||
| Address | What | Token | Documented in |
|
||
|---|---|---|---|
|
||
| `GET /api/heartbeat/<token>[/start\|/fail]` | A cron job says it ran | in the address | [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md) |
|
||
| `GET /metrics` | Prometheus text format | `Authorization: Bearer hlm_m_…` | [PROMETHEUS-GRAFANA.md](PROMETHEUS-GRAFANA.md) |
|
||
| `GET /api/public/calendar/<token>.ics` | A calendar feed of what is coming up | in the address (a share link) | [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md) |
|
||
| `GET /api/public/status/<token>`, `/api/public/wall/<token>` | The data behind a shared status page and wall display | in the address (a share link) | Settings → Share links |
|
||
| `GET /health` | Is the app up? | none | answers `{"ok":true}` |
|
||
|
||
## Reading the API safely
|
||
|
||
- Treat a token like a password: it can read everything its owner can. Give each script its own (so one can be removed alone), choose the shortest life that suits, and keep it in a secret store, not in a repository.
|
||
- Use HTTPS. The token is sent in a header with every request.
|
||
- A removed token stops working at once; if one leaks, remove it under **API tokens** and make another.
|
||
- Every token's last use is shown on the API tokens page, which makes an unused one easy to spot and remove.
|