From 12e6b74ae2902b1757c98033cf659a428e2dfdf6 Mon Sep 17 00:00:00 2001 From: rcourtman Date: Tue, 14 Jul 2026 09:46:12 +0100 Subject: [PATCH] Document the -1 disk usage sentinel in the API reference Guest disk percentages report -1 when a VM is stopped or its guest agent is unavailable (issue #1569); consumers were treating it as a real percentage. --- docs/API.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/API.md b/docs/API.md index e1be789e5..578c53e86 100644 --- a/docs/API.md +++ b/docs/API.md @@ -113,6 +113,8 @@ Query params: Note: `GET /api/resources` is optimized for list views. Some large, platform-specific fields may be omitted from the list response and are only returned by `GET /api/resources/{id}`. +Note: guest disk usage percentages use `-1` as an "unknown" sentinel — reported when a VM is stopped or its guest agent is unavailable, so there is no filesystem view to measure. Consumers should treat negative values as "no data", not as a percentage; the accompanying `diskStatusReason` field (e.g. `vm-stopped`, `agent-disabled`) says why. + `GET /api/resources/stats` Returns aggregations (counts + health rollups).