Files
Homelab-manager/docs/API.md
T
bobbanandClaude Sonnet 5.5 a94899865e Close an alert: dealt with or accepted, hidden until it gets worse
Close... on the Alerts page hides an alert with no end, with an optional reason
that is also written on its incident. It opens again only if it gets more
serious than when it was closed (said once) or the problem has been gone for
half an hour; Open again brings it back at once.

Built on the snooze table (kind, severity and note columns), so everything that
holds back snoozed alerts holds back closed ones. Audit log, change log and
/api/v1 alerts carry it.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-25 20:55:39 +01:00

409 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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,
"closed": 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. |
| `closed` | `{ by, at, note }` when somebody has closed it (it is also `silenced`; a closed alert has no end — it opens again if it gets worse or has been gone for half an hour); `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,
"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`
```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 /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](WEBHOOKS.md#buttons-on-notifications) |
| `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.