From 3a952350bf5b5b38a7db1208ed3c910ded7b4b24 Mon Sep 17 00:00:00 2001 From: Brad Kollmyer Date: Tue, 14 Jul 2026 13:49:48 -0700 Subject: 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 --- docs/automation/vyos-api.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) 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 -- cgit v1.2.3