Quick start

From nothing to a notification on your desktop. Only one value is yours to fill in: the address of this API.

1. Create an account

Open /register. Name, email and your site's exact HTTPS address are all required — the email is how an operator would reach you about the site, and it is never published. You get one account per website, with two keys: a public key (pub_…) and a secret key (cn_live_…). Copy both; they are shown once.

2. Verify the service is reachable

curl -s https://YOUR-API-HOST/health

The same information is rendered as a page at /status, together with the account lifecycle and a per-notification delivery view — handy when you would rather not read JSON.

{
  "success": true,
  "service": "creator-notify",
  "version": "1.0.0",
  "status": "ok",
  "environment": "production",
  "time": "2026-01-31T12:00:00.000Z",
  "checks": { "database": "ok" }
}

A 503 with "database": "unavailable" means the instance you are calling is not fully configured — that is an operator problem, not something your integration can fix.

3. Host the SDK and the Service Worker

Both files must be served from your own origin over HTTPS:

# download them from this API
curl -O https://YOUR-API-HOST/sdk/creator-notify.js
curl -O https://YOUR-API-HOST/sdk/service-worker.js

# then put them at the root of your site:
# https://example.com/creator-notify.js
# https://example.com/service-worker.js   ← must be reachable at the root scope

A Service Worker served from another origin cannot control your pages, so copying these two files onto your own domain is not optional.

4. Add the button

<button id="enable-notifications" type="button">Enable notifications</button>
<p id="status" role="status"></p>

<script src="/creator-notify.js"></script>
<script>
  const notify = new CreatorNotify({
    websiteId: 'pub_8d1f0c...',          // public key — safe to publish
    apiBaseUrl: 'https://YOUR-API-HOST',
    serviceWorkerPath: '/service-worker.js'
  }).init();

  const status = document.getElementById('status');

  document.getElementById('enable-notifications').addEventListener('click', async () => {
    try {
      await notify.subscribe();
      status.textContent = 'Subscribed. You will get notifications from this site.';
    } catch (error) {
      status.textContent = `Could not subscribe: ${error.code} — ${error.message}`;
    }
  });
</script>

5. Send a notification

Fastest path: open the demo, paste the secret key, allow notifications, type a message and send.

Or from your own server:

curl -X POST https://YOUR-API-HOST/v1/notifications \
  -H "Authorization: Bearer $CREATOR_NOTIFY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Hello from Creator Notify",
    "body": "Your first real push notification.",
    "url": "https://example.com/posts/1"
  }'

{
  "success": true,
  "request_id": "req_6bzztuwjevs8ukbgdp4m",
  "notification_id": "ntf_5s2d6u39hcedubqxc1ri6t",
  "status": "completed",
  "accepted_subscriptions": 1,
  "successful_submissions": 1,
  "failed_submissions": 0,
  "invalid_subscriptions": 0,
  "pending_submissions": 0,
  "timestamp": "2026-01-31T12:00:00.000Z",
  "warnings": []
}

Read those counters honestly: successful_submissions means the push service accepted the message. Whether a person saw it is not knowable and is never claimed.

Checklist when nothing arrives

Next

• Integration guides — PHP, Node and plain HTML versions of step 5.
• Notification guide — payload fields and campaign patterns.
• API reference — every route and error.