Bolrach Push API

Quick start

Base URL: https://api.bolrach.io/push/v1

import { BolrachPush } from '@bolrach/push';

const push = new BolrachPush({ apiKey: process.env.BOLRACH_PUSH_KEY });

// One send reaches every device the person has registered.
const message = await push.send({
  app_id: process.env.BOLRACH_PUSH_APP_ID,
  target: { type: 'user', id: 'user_8123' },
  title: 'Your order shipped',
  body: 'Track it in the app.',
  data: { order_id: '8123' },
  priority: 1,
}, { idempotencyKey: 'order-8123-shipped' });

console.log(message.id, message.status);

import os
from bolrach_push import BolrachPush

push = BolrachPush(api_key=os.environ["BOLRACH_PUSH_KEY"])

message = push.send(
    {
        "app_id": os.environ["BOLRACH_PUSH_APP_ID"],
        "target": {"type": "user", "id": "user_8123"},
        "title": "Your order shipped",
        "body": "Track it in the app.",
        "data": {"order_id": "8123"},
        "priority": 1,
    },
    idempotency_key="order-8123-shipped",
)
print(message["id"], message["status"])

Authentication

A server key (bt_live_…) from the API keys page of push.bolrach.io/console. Send it as a bearer token:

curl https://api.bolrach.io/push/v1/... \
  -H "authorization: Bearer $YOUR_KEY"

SDKs

Official clients for Node and Python. Both retry on 429 and 5xx with exponential backoff, obey Retry-After, accept idempotency keys on writes, and raise a typed BolrachPushError carrying status, code, message and requestId — so you branch on the failure instead of parsing a string.

npm install @bolrach/push

pip install bolrach-push

Every endpoint below lists its SDK method name. Anything not yet wrapped is still reachable without waiting for a release:

await client.request('GET', '/some/new/endpoint', { query: { days: 7 } });   // node
client.request('GET', '/some/new/endpoint', query={'days': 7})               # python

Errors and retries

Errors are JSON: {"error": {"code": "...", "message": "..."}}. The HTTP status carries the category, the code carries the specific reason.

Endpoints

await client.send({ /* body */ });

client.send({...})

await client.getMessage(messageId);

client.get_message(message_id)

await client.messageTrace(messageId);

client.message_trace(message_id)

await client.registerInstallation({ /* body */ });

client.register_installation({...})

await client.registerUser({ /* body */ });

client.register_user({...})

await client.receipt({ /* body */ });

client.receipt({...})

await client.listApps();

client.list_apps()

await client.createApp({ /* body */ });

client.create_app({...})

await client.getApp(appId);

client.get_app(app_id)

await client.appStats(appId);

client.app_stats(app_id)

await client.appInsights(appId);

client.app_insights(app_id)

await client.listInstallations(appId);

client.list_installations(app_id)

await client.listDeliveries(appId);

client.list_deliveries(app_id)

await client.listWebhooks();

client.list_webhooks()

await client.createWebhook({ /* body */ });

client.create_webhook({...})

await client.testWebhook(webhookId);

client.test_webhook(webhook_id)

await client.listTemplates();

client.list_templates()

await client.createTemplate({ /* body */ });

client.create_template({...})