Install the SDK

Get an API key

On your app's Setup tab, click Generate API key. The key looks like tmwd_… and is shown once — we store only a hash.

Put it in your environment:

TMWD_API_KEY=tmwd_your_key_here

Rotating creates a new key and kills the old one instantly. Keys are per-app, and requests are limited to 120 per minute per app — heartbeat on your schedule, not in a hot loop.

Node.js / Next.js

npm install @tellmewhendown/node

The client reads TMWD_API_KEY on its own, has zero dependencies, and never throws — a monitoring hiccup will not crash the thing it's monitoring.

import { tmwd } from "@tellmewhendown/node";

// After a cron job succeeds:
await tmwd.heartbeat("nightly-backup");

// Or wrap the whole job — heartbeats only if it succeeds:
await tmwd.beat("nightly-backup", async () => {
  await runBackup();
});

// Report a health check with detail:
await tmwd.check("db", "ok", { latency_ms: 12 });

Python

pip install tellmewhendown

Same behavior: standard library only, reads TMWD_API_KEY, never raises.

import tellmewhendown as tmwd

# After a job succeeds:
tmwd.heartbeat("nightly-backup")

# Or as a decorator — heartbeats only when the function succeeds:
@tmwd.beat("nightly-backup")
def run_backup():
    ...

# Report a health check:
tmwd.check("db", "ok", latency_ms=12)

Anything else: plain curl

The SDKs are thin wrappers over two endpoints — any language that can make an HTTP request works.

# A heartbeat ("this job just ran"):
curl -s -X POST https://ingest.tellmewhendown.com/api/ingest/heartbeat \
  -H "Authorization: Bearer $TMWD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"nightly-backup"}'

# A health check ("this dependency is ok/failing"):
curl -s -X POST https://ingest.tellmewhendown.com/api/ingest/check \
  -H "Authorization: Bearer $TMWD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"type":"db","status":"ok","latency_ms":12}'

The type is any lowercase slug you choose (nightly-backup, stripe-webhook, db) — each one becomes its own monitor on the app page.

How silence detection works

Send a heartbeat a couple of times and we learn its rhythm — a monitor that reports hourly is expected hourly, and when it goes quiet past a grace window, you get an email. No schedule configuration needed.

Don't want to wait for the rhythm to be learned? Declare monitors up front — this also covers the worst case, a job that never runs even once:

curl -s -X POST https://ingest.tellmewhendown.com/api/ingest/declare \
  -H "Authorization: Bearer $TMWD_API_KEY" \
  -H "content-type: application/json" \
  -d '{"monitors":[{"kind":"heartbeat","type":"nightly-backup","interval_seconds":86400}]}'

(The SDKs expose this as tmwd.declare(…).) And if a key is created but no signal ever arrives, we nudge you once after 24 hours — the most common failure mode is the integration that never shipped.