Documentation: guides in docs/, and the reference docs brought up to date
- New docs/ folder: SSO, API, Prometheus and Grafana, webhooks, heartbeats and calendar, how monitoring works, and an index; the old root API.md is split across them - Read API: alerts carry snoozedUntil - DATABASE.md: table and migration counts, indexes, relations, integration config, settings and internal flags, delete rules, retention - ROLES.md: the sidebar table rebuilt from the menu - NOTIFICATIONS.md, INTEGRATIONS.md, BACKUP.md, AGENT_UPDATE.md: what had drifted - README: links to the guides; accounts cannot be deleted in the app Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
24ae8db380
commit
c2e76262ca
17 files changed
+1773
-334
No files matched your search
+377
@@ -0,0 +1,377 @@
|
||||
# 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/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/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.
|
||||
Reference in new issue
Block a user