Quickstart

Send your first push notification in under five minutes. This guide walks you through creating a push app, registering a subscriber, sending a notification, and checking delivery stats.

Prerequisites

• A Krafter account (invite-only -- request access at app.krafter.dev)
• An API key with push:write scope

Step 1: Create a Push App

Push apps represent a notification channel for your project. Each app gets its own VAPID keypair, subscribers, and analytics.

curl -X POST https://app.krafter.dev/api/v1/push/apps \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App"
  }'

{
  "data": {
    "id": "c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "name": "My App",
    "vapid_public_key": "BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LNgKQ...",
    "vapid_private_key": "UQ1-GKEZ9q7JxB...",
    "subscriber_count": 0,
    "settings": {},
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Save both the app id and the vapid_public_key. You will need the public key to subscribe browsers via the Push API.

WARNING

The vapid_private_key is only returned on creation. Store it securely if you need it for custom server-side integrations. For standard use, Krafter handles signing internally.

Step 2: Register a Subscriber

Register a device or browser endpoint as a subscriber. For Web Push, the token is the whole PushSubscription as JSON — JSON.stringify(subscription) of what PushManager.subscribe() returned, with its endpoint and keys.p256dh / keys.auth. The endpoint URL alone is not enough to encrypt a message for that browser, and registration rejects it with a 422 on token.

curl -X POST https://app.krafter.dev/api/v1/push/apps/c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f/subscribers \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "web",
    "token": "{\"endpoint\":\"https://fcm.googleapis.com/fcm/send/eKqL...\",\"keys\":{\"p256dh\":\"BNcRd...\",\"auth\":\"tBHI...\"}}",
    "user_id": "user_123",
    "tags": ["beta"],
    "properties": {
      "plan": "pro"
    }
  }'

{
  "data": {
    "id": "d4e5f6a7-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
    "app_id": "c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "platform": "web",
    "user_id": "user_123",
    "tags": ["beta"],
    "properties": {
      "plan": "pro"
    },
    "status": "active",
    "created_at": "2025-01-15T10:05:00Z"
  }
}

TIP

Tags and properties are optional but recommended. They enable targeted notifications to specific groups of subscribers.

Step 3: Send a Notification

Create a notification. It is sent as soon as it is created; pass scheduled_at to send it later instead. Use the targeting field to control which subscribers receive it.

curl -X POST https://app.krafter.dev/api/v1/push/apps/c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f/notifications \
  -H "Authorization: Bearer kr_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "New Feature!",
    "body": "Check out our latest update",
    "icon": "https://example.com/icon.png",
    "url": "https://example.com/feature",
    "targeting": {
      "type": "tags",
      "tags": ["beta"],
      "match": "any"
    },
    "send": true
  }'

{
  "data": {
    "id": "e5f6a7b8-9c0d-1e2f-3a4b-5c6d7e8f9a0b",
    "app_id": "c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "title": "New Feature!",
    "body": "Check out our latest update",
    "icon": "https://example.com/icon.png",
    "url": "https://example.com/feature",
    "targeting": {
      "type": "tags",
      "tags": ["beta"],
      "match": "any"
    },
    "status": "sending",
    "stats": {},
    "created_at": "2025-01-15T10:10:00Z"
  }
}

To send later, pass "scheduled_at" (ISO 8601) instead of "send": true; the notification is then scheduled and goes out within a minute of that time. There is no draft state in the API.

Step 4: Check Delivery Stats

Fetch daily analytics for your push app to see delivery rates and subscriber growth:

curl https://app.krafter.dev/api/v1/push/apps/c3d4e5f6-7a8b-9c0d-1e2f-3a4b5c6d7e8f/analytics \
  -H "Authorization: Bearer kr_live_abc123def456"

{
  "data": [
    {
      "date": "2025-01-15",
      "sent": 1,
      "delivered": 1,
      "clicked": 0,
      "failed": 0,
      "new_subscribers": 1,
      "unsubscribes": 0
    }
  ]
}

Next Steps

• Web Push Setup -- Service worker registration and browser subscription flow
• Targeting -- Tag-based, user ID, and segment targeting strategies
• API Reference -- Full CRUD endpoints for apps, subscribers, and notifications
• Webhooks -- Get notified on delivery, click, and failure events