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 full subscription endpoint URL returned by the browser's PushManager.subscribe() method.

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": "https://fcm.googleapis.com/fcm/send/eKqL...",
    "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",
    "token": "https://fcm.googleapis.com/fcm/send/eKqL...",
    "user_id": "user_123",
    "tags": ["beta"],
    "properties": {
      "plan": "pro"
    },
    "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 and send it immediately by setting "send": true. 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"
    },
    "stats": {
      "sent": 1,
      "delivered": 0,
      "clicked": 0,
      "failed": 0
    },
    "created_at": "2025-01-15T10:10:00Z"
  }
}

Omit "send": true to create a draft notification that you can review and send later.

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