English
Sign in Start free

Build on Reality Radar

Pull official recalls, end-of-support dates, vulnerabilities and policy changes that match your stack, and get signed webhooks when something affects you.

Open the API reference Create an API key

Quickstart

Create a key in the app under Wire → API keys, then call the API from anywhere. Responses are JSON; times are ISO-8601 UTC.

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/alerts?limit=5
Node.js
const res = await fetch('https://realityradar-7h6.pages.dev/api/v1/public/entities', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.RADAR_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ entityType: 'software_version', displayName: 'Node.js', modelOrVersion: '18.20.0',
    identifiers: { eolProduct: 'nodejs' }, relationship: 'used' }),
});
console.log(res.status, await res.json());
Python
import os, requests
r = requests.get("https://realityradar-7h6.pages.dev/api/v1/public/events", params={"type": "product_recall", "limit": 20},
                 headers={"Authorization": f"Bearer {os.environ['RADAR_KEY']}"}, timeout=10)
r.raise_for_status()
for e in r.json()["items"]:
    print(e["firstSeenAt"], e["title"], e["sourceUrl"])

Authentication

Send the key as a Bearer token. Keys are shown once, stored only as a hash, can expire after 30, 90 or 365 days and can be rolled with a 24-hour overlap.

HTTP
Authorization: Bearer rr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Scopes

Each key carries only the scopes you pick. A request outside them returns 403 insufficient_scope, so a read-only dashboard key can never add items or manage webhooks.

ScopeEndpoints
read:signalsGET /public/events
GET /public/events/{id}
read:entitiesGET /public/entities
write:entitiesPOST /public/entities
read:alertsGET /public/alerts
manage:webhooksGET /public/webhooks
POST /public/webhooks
DELETE /public/webhooks/{id}
GET /public/webhooks/{id}/deliveries
POST /public/webhooks/{id}/deliveries/{deliveryId}/replay

Rate limits

Standard keys allow 60 requests per minute and elevated keys 300. A 429 response means wait and retry; usage per key and endpoint is visible in Wire.

Pagination

List endpoints return items and nextCursor. Pass the cursor back until it is null; cursors are opaque and stable while you page.

Python
cursor = None
while True:
    page = requests.get(f"https://realityradar-7h6.pages.dev/api/v1/public/events", headers=H, params={"limit": 100, "cursor": cursor}).json()
    handle(page["items"])
    cursor = page["nextCursor"]
    if not cursor:
        break

Errors

Errors share one shape with a stable machine code. Treat 5xx and 429 as retryable with backoff, and 4xx as a problem with the request.

JSON
{ "error": { "code": "insufficient_scope", "message": "This key lacks the \"write:entities\" scope" } }
invalid_api_key401Missing, malformed or revoked key
api_key_expired401The key passed its expiry or roll grace period
insufficient_scope403The key lacks the scope this endpoint needs
not_found404Not found, or not visible to this workspace
plan_limit409Free plan item limit reached
ssrf_blocked422URL points at a private or internal address
rate_limited429Too many requests — retry after the window

Webhooks

Webhooks POST a JSON event when an alert at or above your level is created. Delivery logs keep 30 days with status, latency and one-click replay.

HTTP
POST /your/endpoint
Content-Type: application/json
User-Agent: RealityRadar-Webhook/1.0
X-Radar-Signature: t=1761112800,v1=5f2b…a91c,v1=03de…77b0

{"type":"alert.created","alert":{"impactLevel":"critical","matchType":"exact",…},"event":{…}}

Verify signatures

Compute HMAC-SHA256 of t, a dot and the raw body with your secret, compare in constant time with any v1 value and reject timestamps older than five minutes. After a secret rotation two v1 values arrive for 24 hours.

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody: the exact bytes you received (do not re-serialize JSON)
export function verifyRadar(header, rawBody, secret) {
  const parts = header.split(',').map((p) => p.split('='));
  const t = Number(parts.find(([k]) => k === 't')?.[1]);
  const sigs = parts.filter(([k]) => k === 'v1').map(([, v]) => v);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return false;
  const mac = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return sigs.some((v) => v.length === mac.length && timingSafeEqual(Buffer.from(v), Buffer.from(mac)));
}
Python
import hmac, hashlib, time

def verify_radar(header: str, raw_body: bytes, secret: str) -> bool:
    parts = [p.split("=", 1) for p in header.split(",")]
    t = next((int(v) for k, v in parts if k == "t"), None)
    sigs = [v for k, v in parts if k == "v1"]
    if t is None or abs(time.time() - t) > 300:
        return False
    mac = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return any(hmac.compare_digest(mac, s) for s in sigs)
Go
func VerifyRadar(header string, rawBody []byte, secret string) bool {
	var t int64 = -1
	var sigs []string
	for _, p := range strings.Split(header, ",") {
		k, v, ok := strings.Cut(p, "=")
		if !ok { continue }
		if k == "t" { t, _ = strconv.ParseInt(v, 10, 64) }
		if k == "v1" { sigs = append(sigs, v) }
	}
	if t < 0 || math.Abs(float64(time.Now().Unix()-t)) > 300 { return false }
	m := hmac.New(sha256.New, []byte(secret))
	fmt.Fprintf(m, "%d.", t)
	m.Write(rawBody)
	want := hex.EncodeToString(m.Sum(nil))
	for _, s := range sigs {
		if hmac.Equal([]byte(want), []byte(s)) { return true }
	}
	return false
}
curl
# Replay a delivery (fresh timestamp + signature)
curl -X POST -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks/WEBHOOK_ID/deliveries/DELIVERY_ID/replay

Dependencies and OSV

Track packages with a purl such as pkg:npm/lodash and an exact version. Reality Radar checks OSV.dev and marks a match exact when your version is listed as affected. Upload lockfiles or SBOMs in the app under Import.

curl
curl -X POST -H "Authorization: Bearer rr_live_…" -H "Content-Type: application/json" \
  -d '{"entityType":"software_version","displayName":"lodash","modelOrVersion":"4.17.20","identifiers":{"purl":"pkg:npm/lodash"},"relationship":"used"}' \
  https://realityradar-7h6.pages.dev/api/v1/public/entities

Glossary

Terms you will see in responses.

Signal
A detected change event from an official source, with evidence and timestamps.
Beacon
A data source. Tier A is an official regulator or vendor, tier B a curated database.
Match type
exact, strong, probable or weak — how sure we are the event is about your item. Only exact and strong are stated as certain.
Relevance, confidence, severity
Three separate 0–100 scores: does it concern you, how trustworthy is the evidence, how serious is the change.
purl
Package URL, e.g. pkg:npm/lodash, the standard identifier used for OSV matching.
Evidence ledger
A tamper-evident hash chain of every piece of evidence we stored, verifiable by anyone.