Skip to main content
Version: 1.0.0

WUD REST API

Welcome to the WUD REST API documentation.

WUD exposes a comprehensive RESTful API allowing you to inspect monitored containers, check registry updates, trigger notifications manually, and automate container updates from your own scripts, CI/CD pipelines, or homelab dashboards.

🚀 Interactive Playground ("Try it out")​

You can execute live requests against any endpoint directly from this documentation:

  1. In the Server selector on the right panel, select your target Base URL (default is http://localhost:3000).
  2. Fill in the required path, query, or body parameters.
  3. If your WUD instance has authentication enabled, click Authorize and input your credentials.
  4. Click Send API Request to execute the call and inspect the real response.

🌐 Base URL Configuration​

The documentation supports multiple server targets:

  • Local instance (http://localhost:3000): Default local instance when WUD is running on the standard port.
  • Custom instance URL ({url}): Select this option and enter the full base URL of your remote instance (e.g. http://192.168.1.50:3000 or https://wud.myhomelab.net).

💡 CORS Note: When testing from your browser against an instance running on a different port or domain, ensure CORS is allowed or access WUD via your reverse proxy.

🔐 Authentication​

By default, WUD does not enforce authentication unless configured:

  • HTTP Basic: When WUD_AUTH_BASIC_* is enabled, authenticate using HTTP Basic credentials.

📦 Standard Error Responses​

All error responses follow a consistent JSON format:

{
  "error": "NotFound",
  "message": "Container not found"
}

⚠️ Breaking Changes & Migration Notes​

⚠️ API Contract Redesign:

  • Standardized Error Format: In previous versions, error responses were inconsistent (sometimes raw strings, flat objects, or empty responses). All error responses now strictly return a structured JSON object with { "error": "<ErrorType>", "message": "<Details>" }.
  • Authentication: External REST API requests now use standard HTTP Basic Authentication (Authorization: Basic ...). Cookie-based session authentication is no longer exposed as an external API authentication scheme.

Authentication​

HTTP Basic Authentication (when WUD_AUTH_BASIC is enabled)

Security Scheme Type:

http

HTTP Authorization Scheme:

basic