KimePush Docs

Authentication

API requests use Authorization: Bearer <key>.

Project Setup

Contacts and Topics

Contacts are project-scoped profiles with email, external id, name fields, topics, and subscription status. A topic is an audience or subscription such as weekly_digest, product_updates, or launch. Broadcasts match contacts that have every selected topic.

{
  "email": "asha@example.com",
  "external_id": "user_123",
  "first_name": "Asha",
  "last_name": "Kumar",
  "topics": ["weekly_digest", "launch"]
}

// Broadcast matching uses AND semantics:
// contact must have weekly_digest AND launch.

API Reference

{
  "user_id": "user_123",
  "platform": "fcm",
  "token": "device_token...",
  "environment": "production",
  "email": "asha@example.com",
  "first_name": "Asha",
  "topics": ["product_updates"],
  "metadata": {
    "app_version": "2.1.0"
  }
}

{
  "email": "asha@example.com",
  "external_id": "user_123",
  "first_name": "Asha",
  "last_name": "Kumar",
  "topics": ["weekly_digest", "product_updates"]
}

{
  "topics": ["launch", "weekly_digest"]
}

{
  "to": "user_123",
  "title": "Your order shipped",
  "body": "Arrives Thursday",
  "deep_link": "myapp://orders/ORD-9981",
  "data": { "order_id": "ORD-9981" },
  "priority": "high",
  "idempotency_key": "order-shipped-ORD-9981"
}

{
  "channel": "mobile_push",
  "title": "New update available",
  "body": "Version 2.1 is ready to install",
  "topics": ["product_updates"]
}

Webhooks

Add HTTPS endpoints in Project Settings. KimePush signs each payload with the webhook secret shown once at creation time.

const signature = req.headers['x-kimepush-signature'];
const timestamp = req.headers['x-kimepush-timestamp'];
const expected = 'sha256=' +
  crypto.createHmac('sha256', webhookSecret)
        .update(timestamp + '.' + rawBody)
        .digest('hex');

if (!crypto.timingSafeEqual(
  Buffer.from(signature), Buffer.from(expected)
)) throw new Error('Invalid signature');

Status API

GET /status is backed by the KimePush status incident tables, not hardcoded page text. Admin can create and update incidents from the admin console. The endpoint returns overall state and active incidents for the public status page.

curl https://api.kimepush.kimevik.com/status

{
  "status": "operational",
  "incidents": []
}

Error Codes

Every error response has the shape { "error": "<code>", "message": "<detail>" }. error is the stable code to branch on; message is a human-readable detail that can vary per request.

DLQ and Error Management