API Reference

Base URL

https://api.nudgr.dev

Most project-scoped endpoints require:

Authorization: Bearer nk_...

GET /v1/vapid-key/self

Resolve the VAPID public key for the current project API key.

Response:

{
  "publicKey": "BEl..."
}

POST /v1/subscriptions

Create or update a browser push subscription.

{
  "endpoint": "https://push.example.com/...",
  "keys": {
    "p256dh": "...",
    "auth": "..."
  },
  "userAgent": "Mozilla/5.0 ...",
  "tags": ["vip", "zh-CN"]
}

Required fields:

• endpoint
• keys.p256dh
• keys.auth

Optional fields:

• tags: string array stored on the subscription

GET /v1/subscriptions

List project subscriptions.

Query parameters:

• limit default 50, max 200
• offset default 0

DELETE /v1/subscriptions/:id

Delete a subscription by ID.

PATCH /v1/subscriptions/:id/tags

Overwrite the full tag list for a subscription.

{
  "tags": ["vip", "zh-CN"]
}

Required fields:

• tags: string array, use [] to clear tags

POST /v1/subscriptions/unsubscribe

Delete a subscription for the current project by push endpoint.

{
  "endpoint": "https://push.example.com/..."
}

Required fields:

• endpoint

POST /v1/notifications/send

Send a notification to all project subscriptions or to selected subscriber IDs.

{
  "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"]
}

Required fields:

• title

Optional filters:

• subscriberIds: explicit subscription ID allowlist
• targetTags: send to subscriptions matching any provided tag

GET /v1/notifications

List sent notifications.

Query parameters:

• limit default 50, max 200
• offset default 0

GET /v1/notifications/stats

Get daily delivery stats for the current project.

Query parameters:

• days default 30, max 90

Response fields:

• daily
• subscribers
• days

POST /v1/events/click

Records a click event from the service worker and forwards it to project webhooks.

{
  "projectId": "proj_123",
  "notificationId": "notif_123",
  "subscriptionId": "sub_123",
  "title": "Hello!",
  "url": "https://example.com/welcome"
}

Required fields:

• projectId
• notificationId
• subscriptionId
• title

Errors

Common error responses:

{ "error": "title is required" }

{ "error": "Project not found" }

{ "error": "No subscriptions found" }