Send Notifications

Endpoint

POST https://api.nudgr.dev/v1/notifications/send
Authorization: Bearer nk_...
Content-Type: application/json

Minimal request

curl -X POST https://api.nudgr.dev/v1/notifications/send \
  -H "Authorization: Bearer nk_..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Hello!","body":"Your first push notification"}'

Request fields

{
  "title": "Hello!",
  "body": "Optional body text",
  "url": "https://example.com/welcome",
  "icon": "https://example.com/icon.png",
  "subscriberIds": ["sub_123", "sub_456"],
  "targetTags": ["vip", "zh-CN"]
}

• title: required
• body: optional
• url: optional click-through URL
• icon: optional notification icon
• subscriberIds: optional list of subscription IDs to target
• targetTags: optional list of subscription tags to match with any-match semantics

If subscriberIds is omitted, Nudgr sends to all subscriptions in the project.

If targetTags is present, Nudgr only sends to subscriptions whose stored tags match at least one requested tag.

If you provide both subscriberIds and targetTags, Nudgr sends to the intersection of those two filters.

Example response

{
  "notification": {
    "id": "notif_123",
    "title": "Hello!",
    "body": "Your first push notification",
    "url": "https://example.com/welcome",
    "icon": null,
    "sent_count": 42,
    "failed_count": 3,
    "created_at": "2026-03-17 09:29:11"
  },
  "summary": {
    "total": 45,
    "sent": 42,
    "failed": 3,
    "staleRemoved": 1
  }
}

Notes

• sent means the push service accepted the request
• A successful send does not guarantee the user saw the notification
• Failed or expired subscriptions may be removed automatically
• To track clicks, configure Webhooks