Files
Homelab-manager/docs/API.md
T
bobbanandClaude Sonnet 5.5 3cb3e4988f Check a value, not just "is it up": JSON value checks on web endpoints
A web check can read a value out of a JSON answer (power.now, state,
data.result[0].value[1]) and judge it: below, above, equal to, contains, is there.
The value read is shown on the Endpoints page, charted under History, exported as
homelab_endpoint_value and in the read API. A check can also send one header (a
token), stored encrypted, never returned, and not forwarded to another host on a
redirect.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-21 21:13:44 +02:00

24 KiB
Raw Blame History

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

  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

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

{
  "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": [ … ] }
] }
  • 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

{
  "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,
    "value": 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. value is null unless the check judges a value in the answer, and then { "path": "power.now", "operator": "<", "expected": "5000", "unit": "W", "last": "120" } (last is what it read the last time, as text).

/: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. A check that judges a value also has values — { unit, days, points: [{t, v, lo, hi}], latest, lowest, highest } — over as much of that stretch as results are kept (14 days); otherwise values is null.

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 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.

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 /api/alert-actions/<token>, POST /api/alert-actions/<token>/<ack|silence|snooze> The page and the buttons behind a notification a signed token in the address (24 hours, for the alerts in that message) WEBHOOKS.md
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.