API.

Send push notifications programmatically using your group's secret key. No user session required.

Base URL

https://push.haelp.dev

POST /api/push/:id

Send a push notification to all subscribers of a group. Authenticated with the group's secret key.

URL params

id string

The MongoDB ObjectId of the push group.

Request body (JSON)

key string

Required. The group's secret key.

data.title string

Required. Notification title.

data.url string

Optional. URL to open when the notification is clicked. Must be a valid URL.

data.options object

Optional. NotificationOptions — supports body, icon, image, badge, tag, silent, requireInteraction, vibrate, timestamp, and actions (max 2, each with a valid URL in the action field and a title string). The data field is not allowed.

Example

fetch('https://push.haelp.dev/api/push/<id>', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    key: '<your-secret-key>',
    data: {
      title: 'Hello world!',
      url: 'https://example.com',
      options: {
        body: 'This is the notification body.',
        icon: 'https://example.com/icon.png',
        actions: [
          { action: 'https://example.com/yes', title: 'Yes' },
          { action: 'https://example.com/no',  title: 'No' }
        ]
      }
    }
  })
})

Responses

200

{ "success": true } — notification sent to all subscribers.

400

Missing or invalid request fields.

403

Invalid secret key.

404

Group not found.

Note: Invalid subscriptions (e.g. device uninstalled the browser) are automatically removed when a push is sent.

Other endpoints

The following routes are used by the Push web app (session-authenticated) and are not intended for direct API use.

POST /api/create

Create a new push group (requires login).

DELETE /api/delete/:id

Delete a push group and all its subscriptions (requires login, must own group).

POST /api/subscribe/:id

Subscribe the current user's device to a push group (requires login).

POST /api/unsubscribe/:id

Unsubscribe a subscription by its ID (requires login, must own subscription).