How to use Pulsar

Pulsar shows the health of your APIs and services on your phone. You add one endpoint to your backend, GET /pulsar, protect it with one token, and Pulsar reads it. This guide takes about ten minutes, from an empty project to your first notification.

1. What you need

• An API or backend you can deploy, in any language or framework.
• A place to set environment variables (a .env file, your hosting dashboard or your CI secrets).
• Pulsar installed on an iPhone (iOS 15 or later) or Android phone (Android 6 or later).

No account, no SDK and no third-party service are needed.

2. Create a token

Generate a long random token. It is the only key that can read your status, so treat it like a password:

openssl rand -hex 32

You can also use Developer tools › Token generator inside the app, which creates a 256-bit token on your device.

Add it to your server's environment, never to your source code:

PULSAR_ENABLED=true
PULSAR_TOKEN=<your-token>

If PULSAR_ENABLED is not exactly true, or the token is empty, the endpoint must answer 404 Not Found, as if it did not exist.

3. Add GET /pulsar to your API

The endpoint checks your components (database, cache, workers, external services) and returns JSON:

{
  "status": "operational",
  "components": [
    { "name": "API", "state": "operational", "uptime30d": 1 },
    { "name": "PostgreSQL", "state": "operational", "uptime30d": 0.9999 },
    { "name": "Redis", "state": "degraded", "uptime30d": 0.9872 }
  ],
  "checkedAt": "2026-10-03T09:41:00.000Z"
}

The rules that matter:

• Read the token only from the Authorization: Bearer <token> header, and compare it in constant time. Never accept it in the URL.
• A missing or wrong token returns 401 Unauthorized and runs no checks.
• Answer with Content-Type: application/json and Cache-Control: no-store.
• A component that is down is not an error: still return 200 OK, with that component in major_outage.
• uptime30d is a number between 0 and 1 (for example 0.9999 is 99.99%).

A minimal example with Node.js and Express:

import crypto from "node:crypto";
import express from "express";

const app = express();

app.get("/pulsar", async (req, res) => {
  const token = process.env.PULSAR_TOKEN ?? "";
  if (process.env.PULSAR_ENABLED !== "true" || !token) return res.sendStatus(404);

  const given = (req.get("authorization") ?? "").replace(/^Bearer /, "");
  const a = crypto.createHash("sha256").update(given).digest();
  const b = crypto.createHash("sha256").update(token).digest();
  if (!crypto.timingSafeEqual(a, b)) {
    return res.set("WWW-Authenticate", "Bearer").sendStatus(401);
  }

  const db = await checkDatabase(); // "operational" | "degraded" | "major_outage"
  const components = [
    { name: "API", state: "operational", uptime30d: 1 },
    { name: "PostgreSQL", state: db, uptime30d: 0.9999 },
  ];
  const status = components.some((c) => c.state === "major_outage")
    ? "partial_outage"
    : components.some((c) => c.state === "degraded") ? "degraded" : "operational";

  res.set("Cache-Control", "no-store")
    .json({ status, components, checkedAt: new Date().toISOString() });
});

Complete, tested guides for Node.js, Express, Fastify, NestJS, Next.js, FastAPI, Django, Laravel, Go, Rust, .NET and Spring Boot are inside the app in Setup Guide, together with the full Pulsar Protocol specification.

Deploy, then check it from your computer:

curl -H "Authorization: Bearer $PULSAR_TOKEN" https://api.example.com/pulsar

4. Add your project in Pulsar

Tap + on the Projects screen and fill in:

Tap Test Connection. Pulsar checks, step by step, that the server is reachable, that the token is accepted, that the endpoint exists and that the response follows the protocol, and shows how many components it found. Fix anything marked in red, then tap Add Project.

The token is saved in the iOS Keychain or Android Keystore and is never shown again. You can replace it later from the project menu.

5. Read the status

The Projects screen shows every project with its global status, response time, uptime and a 24-hour timeline. Open a project to see each component.

When Pulsar cannot reach your endpoint (no network, timeout, TLS problem, wrong token) the project shows why in plain words, and keeps the last known component states so you still see what was working.

The project screen also shows Insights for the last 24 hours or 7 days: how often the endpoint was reachable and operational, latency percentiles and the periods with problems.

6. Activity and notifications

Pulsar records changes, not every check: a component degrading, an outage, a recovery, an endpoint becoming unreachable or reachable again. You find them in the Activity tab, grouped by day, with how long each incident lasted.

The first time you add a project, Pulsar asks for permission to send notifications. In Settings › Notifications you choose whether to be notified of state changes and of recoveries. To silence one project for a while (during a deployment, for example), open its menu and choose Mute notifications. Muted projects are still checked and recorded.

7. How often Pulsar checks

While Pulsar is open, every project is checked at the interval you choose in Settings › Check interval (30 seconds to 30 minutes, or manually). You can always pull down to check now.

When the app is closed, iOS and Android decide when background checks run: at most every 15 minutes, often less, and never while the phone restricts background activity. A phone cannot monitor 24/7. Use Pulsar to keep an eye on your projects, not as your only alerting system for critical services.

8. Local development

To check an API running on your computer:

• On a phone, localhost means the phone itself. Use your computer's local IP instead, e.g. http://192.168.1.42:3000, and make sure both are on the same Wi-Fi.
• The Android emulator reaches your computer at http://10.0.2.2:<port>. The iOS Simulator can use http://localhost:<port>.
• Plain HTTP is only allowed for the Development environment and private network addresses, and Pulsar marks it Not Secure. Production always requires HTTPS.
• On iPhone, allow Local Network for Pulsar when asked (Settings › Privacy & Security › Local Network).

9. Developer tools

Tap the code icon on the Projects screen. Everything runs on your device:

• Payload validator — paste a response and check it against the protocol.
• Request snippets — curl, HTTPie, fetch, Python and a GitHub Actions check, with $PULSAR_TOKEN instead of your token.
• Token generator — secure 256-bit tokens and the matching .env line.
• SLA calculator — downtime allowed by 99.9%, 99.99% and other targets.
• Latency benchmark — sequential requests to a project with p50, p95 and jitter.
• TLS inspector — certificate issuer, expiry and days left for any host.
• Incident report — a Markdown summary of a project's incidents, ready for postmortems.

10. Security and privacy

• Tokens live only in the Keychain or Keystore and travel only in the Authorization header.
• Certificate validation is always on, HTTPS-to-HTTP redirects are blocked, and the token is never sent to a different host.
• App Lock (Settings › Security) protects Pulsar with Face ID, fingerprint or your device passcode, after the delay you choose.
• Pulsar has no account, no servers and no analytics. Read the Privacy Policy.

11. Make it yours

• Appearance: system, light or dark.
• App icon: Light, Dark, Pulse or Ring (Settings › App icon). On Android the new icon appears after you leave the app.
• Language: English, Español, Français, Deutsch, Русский, 中文, العربية or Norsk bokmål (Settings › Language).
• Order and filters: drag projects to reorder them; filter by status.
• Export and import: move your projects to another phone with a JSON file. Tokens are never exported; add them again on the new phone.

12. Troubleshooting

Still stuck? Write to info@arkplatforms.eu and include, if you can, the file from Settings › Developer › Diagnostics › Export diagnostics (it never contains tokens).