Skip to content

Ntfy — Reference

  • Website: https://ntfy.sh
  • API docs: https://docs.ntfy.sh
  • GitHub: https://github.com/binwiederhier/ntfy
  • Android app: https://play.google.com/store/apps/details?id=io.heckel.ntfy
  • iOS app: https://apps.apple.com/us/app/ntfy/id1625396347

Authentication

No authentication configured. All topics are open for publish and subscribe.

# No auth headers needed
curl -s https://ntfy.eva-00.network/...

API — Publishing

Publish a simple message

curl -d "Backup complete" https://ntfy.eva-00.network/homelab

Publish with title and priority

curl -s -X POST https://ntfy.eva-00.network/homelab \
  -H "Title: Backup failed" \
  -H "Priority: high" \
  -H "Tags: warning,backup" \
  -d "Vault snapshot backup returned exit code 1"

Publish JSON

curl -s -X POST https://ntfy.eva-00.network/ \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "homelab",
    "title": "Deploy complete",
    "message": "Jellyfin deployed successfully",
    "priority": 3,
    "tags": ["white_check_mark", "jellyfin"]
  }'

Publish with a click action (URL)

curl -s -X POST https://ntfy.eva-00.network/homelab \
  -H "Title: New episode available" \
  -H "Click: https://jellyfin.eva-00.network" \
  -d "One Piece S01E1050 is ready to watch"

Publish with an attachment (URL)

curl -s -X POST https://ntfy.eva-00.network/homelab \
  -H "Attach: https://example.com/image.jpg" \
  -d "Image attached"

Priority levels

Priority Name Effect
1 min No sound, no vibration
2 low No sound
3 default Sound
4 high Sound, may override DND
5 urgent Sound, bypasses DND, persistent notification

API — Subscribing

Subscribe via SSE (Server-Sent Events)

curl -s https://ntfy.eva-00.network/homelab/sse

Subscribe via JSON stream

curl -s https://ntfy.eva-00.network/homelab/json

Subscribe to multiple topics

curl -s https://ntfy.eva-00.network/homelab,mediabot,backup/json

Poll for cached messages (since timestamp)

curl -s "https://ntfy.eva-00.network/homelab/json?poll=1&since=1h"

Subscribe via WebSocket

wss://ntfy.eva-00.network/homelab/ws

API — Server Info

Health check

curl -s https://ntfy.eva-00.network/v1/health
# Returns {"healthy":true}

Server info

curl -s https://ntfy.eva-00.network/v1/info

CLI

Ntfy has a CLI but it is not installed on the server (runs as Docker). Use curl or the mobile app instead.

# If ntfy CLI were installed:
ntfy publish homelab "Hello from CLI"
ntfy subscribe homelab

Active Topics in This Homelab

Topic Publishers Purpose
mediabot mediabot-mcp, n8n Media download notifications
homelab Backrest hooks, backup scripts Infrastructure alerts
mac-backup backup-to-cajita.sh Mac backup progress/completion

What the API/CLI Cannot Do

Gap Workaround
Cannot list all active topics via API No discovery endpoint; topics are implicit
Cannot delete/purge messages from a topic Messages expire based on cache duration config
Cannot manage users/ACLs via API (auth disabled) Enable auth in server.yml and use ntfy user CLI commands
Cannot set per-topic retention Global cache duration only (cache-duration in server.yml)
CLI not available on server (Docker) Use curl or docker exec ntfy ntfy ...
Cannot send email notifications without SMTP config Configure smtp-sender-* settings in server.yml
Cannot view notification history in web UI beyond cache window Messages expire after the configured cache duration