1 files changed, 78 insertions, 0 deletions
diff --git a/docs/vyos-api.md b/docs/vyos-api.md
new file mode 100644
index 0000000..33a443f
--- /dev/null
+++ b/docs/vyos-api.md
@@ -0,0 +1,78 @@
+# VyOS API Command Reference
+
+The JSON definitions for each VyOS REST API command supported by PyVyOS are located in `docs/development/vyos_api/`.
+
+## Location
+
+All JSON specification files are stored in: **`docs/development/vyos_api/`**
+
+These JSONs are reference documentation and are:
+- Used for API documentation generation
+- Available for validation and testing
+- Not packaged with the library (reference only)
+
+## Files
+
+- `schema.json` - JSON Schema definition for all API commands
+- Individual command files:
+  - `configure-set.json` - Set configuration values
+  - `configure-delete.json` - Delete configuration values
+  - `configure-multiple-op.json` - Execute multiple operations atomically
+  - `retrieve-show-config.json` - Retrieve configuration in show format
+  - `retrieve-return-values.json` - Retrieve specific configuration values
+  - `show.json` - Execute show commands
+  - `generate.json` - Generate configuration elements (SSH keys, etc.)
+  - `reset.json` - Reset configuration elements
+  - `config-file-save.json` - Save configuration to file
+  - `config-file-load.json` - Load configuration from file
+  - `reboot.json` - Reboot the device
+  - `poweroff.json` - Power off the device
+  - `image-add.json` - Add VyOS system image
+  - `image-delete.json` - Delete VyOS system image
+
+## Structure
+
+Each JSON file follows this structure:
+
+```json
+{
+  "command": "command-name",
+  "operation": "operation-name",
+  "description": "Description of what the command does",
+  "endpoint": "/endpoint-path",
+  "method": "HTTP_METHOD",
+  "request": {
+    "payload": { ... },
+    "example": { ... }
+  },
+  "response": {
+    "success": { ... },
+    "error": { ... }
+  },
+  "parameters": { ... },
+  "python_usage": "device.method_name(...)"
+}
+```
+
+## Usage
+
+These JSON files can be used for:
+- API documentation generation
+- Request validation
+- Response schema validation
+- Client library code generation
+- Testing and mocking
+
+## JSON Schema
+
+The `schema.json` file defines the complete structure for all API commands and can be used with JSON Schema validators.
+
+## Path Parameter Handling
+
+**Important:** The `path` parameter handling varies by command:
+
+- **config-file commands** (`save`, `load`): The VyOS API requires `path` to be present in the payload, even if empty (`[]`). PyVyOS handles this automatically.
+- **Other commands**: When `path` is empty or not provided, it may be omitted from the payload for cleaner requests.
+
+See individual JSON files in `docs/development/vyos_api/` for specific parameter requirements.
+