Update docs and write troubleshooting steps to debug no reciving ban/unban events

docs/api.md

@@ -4,8 +4,12 @@ This is a short index for operators. The UI primarily uses these endpoints. Path
 
 ## Authentication
 
-- When OIDC is enabled, most `/api/*` endpoints require an authenticated session.
-- Callback endpoints are authenticated using `X-Callback-Secret`.
+- When OIDC is enabled, all `/api/*` endpoints (including WebSocket) require an authenticated session, except the callback endpoints.
+- Callback endpoints (`/api/ban`, `/api/unban`) are authenticated using `X-Callback-Secret`.
+
+## Input validation
+
+All endpoints that accept IP addresses validate them server-side using Go's `net.ParseIP` / `net.ParseCIDR`. Requests with invalid IPs receive a `400 Bad Request` response. This applies to ban/unban callbacks, manual ban/unban from the dashboard, and the advanced actions test endpoint.
 
 ## Common headers
 
@@ -14,49 +18,79 @@ This is a short index for operators. The UI primarily uses these endpoints. Path
 
 ## Endpoints
 
-Server management
-- `GET /api/servers`
-- `POST /api/servers`
-- `DELETE /api/servers/:id`
-- `POST /api/servers/:id/test`
+### Server management
+- `GET /api/servers` -> List configured servers
+- `POST /api/servers` -> Create or update a server
+- `DELETE /api/servers/:id` -> Delete a server
+- `POST /api/servers/:id/default` -> Set server as default
+- `POST /api/servers/:id/test` -> Test server connectivity
+- `GET /api/ssh/keys` -> List available SSH keys
 
-Jails and configuration
-- `GET /api/summary`
-- `GET /api/jails/manage`
-- `POST /api/jails/manage`
-- `GET /api/jails/:jail/config`
-- `POST /api/jails/:jail/config`
-- `POST /api/jails/:jail/unban/:ip`
-- `POST /api/jails/:jail/ban/:ip`
+### Jails and configuration
+- `GET /api/summary` -> Dashboard summary (jails, banned IPs per server)
+- `GET /api/jails/manage` -> List jails with enabled/disabled status
+- `POST /api/jails/manage` -> Update jail enabled/disabled state
+- `POST /api/jails` -> Create a new jail
+- `DELETE /api/jails/:jail` -> Delete a jail
+- `GET /api/jails/:jail/config` -> Get jail/filter configuration
+- `POST /api/jails/:jail/config` -> Update jail/filter configuration
+- `POST /api/jails/:jail/logpath/test` -> Test log path accessibility
+- `POST /api/jails/:jail/unban/:ip` -> Unban an IP from a jail
+- `POST /api/jails/:jail/ban/:ip` -> Ban an IP in a jail
 
-Events and analytics
-- `GET /api/events/bans`
-- `GET /api/events/bans/stats`
-- `GET /api/events/bans/insights`
+### Events and analytics
+- `GET /api/events/bans` -> List ban/unban events (paginated, filterable)
+- `DELETE /api/events/bans` -> Delete all stored ban events
+- `GET /api/events/bans/stats` -> Ban statistics (counts, timeseries)
+- `GET /api/events/bans/insights` -> Ban insights (countries, top IPs, top jails)
 
-Settings
-- `GET /api/settings`
-- `POST /api/settings`
-- `POST /api/settings/test-email`
+### Advanced actions
+- `GET /api/advanced-actions/blocks` -> List permanent block records
+- `DELETE /api/advanced-actions/blocks` -> Delete all permanent block records
+- `POST /api/advanced-actions/test` -> Manually test block/unblock on configured integration
 
-Filter debugging
-- `GET /api/filters`
-- `POST /api/filters/test`
+### Settings
+- `GET /api/settings` -> Get current application settings
+- `POST /api/settings` -> Update application settings
+- `POST /api/settings/test-email` -> Send a test email
 
-Service control
-- `POST /api/fail2ban/restart`
+### Filter management
+- `GET /api/filters` -> List available filters
+- `GET /api/filters/:filter/content` -> Get filter file content
+- `POST /api/filters` -> Create a new filter
+- `POST /api/filters/test` -> Test filter regex against log lines
+- `DELETE /api/filters/:filter` -> Delete a filter
 
-Callbacks (Fail2Ban actions)
-- `POST /api/ban`
-- `POST /api/unban`
+### Service control
+- `POST /api/fail2ban/restart` -> Restart / Reloads the Fail2Ban service
+
+### Version
+- `GET /api/version` -> Get running version and optional update check
+
+### WebSocket
+- `GET /api/ws` -> WebSocket endpoint (upgrade)
+
+The WebSocket connection streams, real-time events to the frontend:
+- `heartbeat` -> periodic health check (~30s)
+- `console_log` -> debug console log lines (when debug mode is enabled)
+- `ban_event` -> real-time ban event broadcast
+- `unban_event` -> real-time unban event broadcast
+
+The WebSocket enforces same-origin policy via the `Origin` header and requires authentication when OIDC is enabled.
+
+### Callbacks (Fail2Ban actions)
+- `POST /api/ban` -> Receive ban notification from Fail2Ban
+- `POST /api/unban` -> Receive unban notification from Fail2Ban
 
 Callbacks require:
 - Header: `X-Callback-Secret: <secret>`
 - JSON body fields (typical): `serverId`, `ip`, `jail`, `hostname`, `failures`, `logs`
 
-Authentication routes (OIDC)
-- `GET /auth/login`
-- `GET /auth/callback`
-- `GET /auth/logout`
-- `GET /auth/status`
-- `GET /auth/user`
+All IPs in callback payloads are validated before processing.
+
+### Authentication routes (OIDC)
+- `GET /auth/login` -> Initiate OIDC login flow
+- `GET /auth/callback` -> OIDC provider callback
+- `GET /auth/logout` -> Logout and clear session
+- `GET /auth/status` -> Check authentication status
+- `GET /auth/user` -> Get current user info