API Reference

API Reference

release-notifier exposes a small HTTP API on port 8080. All endpoints are read-only except POST /api/check.

---

GET /api/health

Returns the current status of the service.

Authentication: None required

Response:

{
  "status": "ok",
  "docker_socket": true,
  "watched": 14,
  "digest_tracking": 11,
  "known_versions": 14,
  "last_check_at": "2026-04-19T18:00:03.000000+00:00",
  "last_check_ok": true,
  "next_check_at": "2026-04-20T00:00:03.000000+00:00",
  "check_running": false,
  "auth_enabled": true,
  "ai_provider": "Claude",
  "notify_provider": "both"
}

Field	Description
status	Always "ok" if the service is running
docker_socket	Whether the Docker socket is connected
watched	Number of containers being monitored
digest_tracking	Containers with an image field set
known_versions	Number of containers with a known version
last_check_at	ISO timestamp of the last check
last_check_ok	Whether the last check completed without error
next_check_at	ISO timestamp of the next scheduled check
check_running	Whether a check is currently in progress
auth_enabled	Whether API key auth is enabled
ai_provider	Active AI provider
notify_provider	Active notification provider

---

GET /api/updates

Returns the last 10 detected updates.

Authentication: None required

Response:

{
  "updates": [
    {
      "container": "Vaultwarden",
      "github": "dani-garcia/vaultwarden",
      "version": "1.35.5",
      "running_version": "1.35.4",
      "pull_status": "pull_required",
      "urgency": "urgent",
      "published": "2026-04-12T10:00:00Z",
      "summary": "This is a security patch release...",
      "release_url": "https://github.com/dani-garcia/vaultwarden/releases/tag/1.35.5",
      "detected_at": "2026-04-12T18:00:03.000000+00:00"
    }
  ],
  "count": 1
}

Field	Description
pull_status	up_to_date, pull_required, or unknown
urgency	urgent, high, or default
running_version	Version currently running (from OCI labels)

---

GET /api/latest

Returns only the most recent update. Useful for Homepage customapi widget.

Authentication: None required

Response:

{
  "container": "Vaultwarden",
  "version": "1.35.5",
  "running_version": "1.35.4",
  "pull_status": "pull_required",
  "urgency": "urgent",
  "summary": "This is a security patch release...",
  "url": "https://github.com/dani-garcia/vaultwarden/releases/tag/1.35.5",
  "detected": "2026-04-12"
}

---

POST /api/check

Triggers an immediate release check outside of the normal schedule.

Authentication: Required if API_KEY env var is set. Pass the key via X-API-Key header.

Request:

# Without API key
curl -X POST http://localhost:8080/api/check -H "Content-Length: 0"

# With API key
curl -X POST http://localhost:8080/api/check \
  -H "X-API-Key: your_key" \
  -H "Content-Length: 0"

Response (202):

{"status": "check triggered"}

Response (409 — check already running):

{"status": "already running"}

Response (401 — invalid or missing API key):

Unauthorized

---

GET /dashboard

Returns an HTML dashboard page suitable for embedding as a Homepage iframe widget.

Authentication: None required

Usage in Homepage services.yaml:

- Release Notifier:
    icon: mdi-bell-ring
    href: https://releases.yourdomain.com
    widget:
      type: iframe
      src: http://release-notifier:8080/dashboard
      classes: h-96

---

GET /

Returns a JSON overview of the service.

Authentication: None required

Response:

{
  "service": "release-notifier",
  "watched": ["Jellyfin", "Immich", "Vaultwarden"],
  "updates": [...]
}