vyos-api: T9089: document /retrieve showConfig on empty paths

showConfig returns HTTP 400 'Configuration under specified path is
empty' for schema-valid but unconfigured paths; recommend probing with
exists or treating that error as an empty subtree.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

1 files changed, 21 insertions, 0 deletions

diff --git a/docs/automation/vyos-api.md b/docs/automation/vyos-api.md
index 1c51cc01..c7f30842 100644
--- a/docs/automation/vyos-api.md
+++ b/docs/automation/vyos-api.md
@@ -266,6 +266,27 @@ response:
 }
 ```
 
+Note that `showConfig` returns an error (HTTP 400) for a path that is valid
+in the schema but has no configuration under it:
+
+```none
+curl -k --location --request POST 'https://vyos/retrieve' \
+--form data='{"op": "showConfig", "path": ["firewall", "ipv4", "forward"]}' \
+--form key='MY-HTTPS-API-PLAINTEXT-KEY'
+
+response:
+{
+   "success": false,
+   "data": null,
+   "error": "Configuration under specified path is empty"
+}
+```
+
+Automation that compares a desired state against a fresh or partially
+configured system should either probe the path with `exists` first, or
+treat this specific error as "no configuration present" rather than as a
+failed request.
+
 
 ### /reset