- 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>
23 KiB
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 |
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 |
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 for /metrics, WEBHOOKS.md for being told when something
happens instead of asking, HEARTBEATS-AND-CALENDAR.md, MONITORING.md for what the alert fields mean.
The read API
Getting a token
- Sign in, open the user menu → API tokens. This is open to everyone signed in, whatever their role.
- Give the token a name (e.g.
Home Assistant) and choose how long it lasts: 30, 90 or 365 days, or until removed. - 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
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:
401with a JSON body andWWW-Authenticate: Bearer realm="homelab-manager". - Only
GETandHEAD. Any other verb gets405({"error":"read_only"}) withAllow: GET, HEAD— with a token or without. - Limits: 300 requests a minute from one address (
429beyond that). Answers carryCache-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 (createdAton a server) areYYYY-MM-DD HH:MM:SSin UTC. - Sizes are bytes. Percentages are 0–100 (not 0–1).
urlis a full address into the app, built fromAPP_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 hasoperatingSystem: null. - Errors are JSON:
{ "error": "<code>", "message": "…" }witherrorone ofunauthorized,read_only,not_found,invalid_id. - Unknown addresses under
/api/v1get404and point atGET /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
{
"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
{ "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=
{ "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": [ … ] }
] }
kindiscpu,memordisk; a disk'smetricisdisk:<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
loandhi(the lowest and highest in that hour or day). - A disk's
trendis a straight-line fit:perDayis points per day,fitis how straight (0–1),daysToFullis set only when the disk is rising steadily.nullfor CPU and memory, and for a disk with too little history.
GET /api/v1/alerts
{
"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.
{ "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.
{ "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
{ "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
{ "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
{ "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?
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):
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:
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+):
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:
# secrets.yaml
hlm_auth: "Bearer hlm_p_xxxxxxxxxxxxxxxxxxxxxxxx"
# 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.
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
systemis optional, and a part that is malformed is dropped rather than costing the report. Text is trimmed to a sane length.tasksmay be[](but is required). - Answers:
202with{ "ok": true, "taskCount": 1 }when the report is taken;401for 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_typeiscron,systemd_timerorwindows_task.os_typeis recorded only if it islinuxorwindows. 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.
How the figures are used is in 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 |
GET /metrics |
Prometheus text format | Authorization: Bearer hlm_m_… |
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 |
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.