English
Sign in Start free

API reference

Every public endpoint, the scope it needs and real request and response examples. Generated at build time from our OpenAPI 3.1 file.

OpenAPI 3.1.0 · v1.1.0 · Developer guide

GET /public/events

List public change events

Newest first. Private page-watch events are never listed.

Required scope: read:signals

Parameters

typequerystring (product_recall, vehicle_recall, food_drug_recall, end_of_life, end_of_support_upcoming, new_release, …)Filter by event type
qquerystringFull-text search
regionquerystringCountry code; GLOBAL events are always included
limitqueryintegerPage size
cursorquerystringOpaque cursor from the previous page's `nextCursor`

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/events

Response (200)

JSON
{
  "items": [
    {
      "id": "7f1c2b3a-0d9e-4c8b-9a77-1e2f3a4b5c6d",
      "eventType": "product_recall",
      "title": "Ceramic heater HX-200 recalled for overheating",
      "summary": "Voluntary recall of units made 2024-11 to 2025-02.",
      "region": "KR",
      "sourceUrl": "https://www.safetykorea.kr/recall/…",
      "sourcePublishedAt": "2026-10-18T00:00:00.000Z",
      "firstSeenAt": "2026-10-19T03:10:00.000Z",
      "lastVerifiedAt": "2026-10-22T03:10:00.000Z",
      "confidence": 85,
      "severity": 80
    }
  ],
  "nextCursor": "MjAyNi0xMC0xOV…"
}

GET /public/events/{id}

Get one event with sources and evidence

Required scope: read:signals

Parameters

idpath *string

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/events/ID

Response (200)

JSON
{
  "id": "7f1c2b3a-0d9e-4c8b-9a77-1e2f3a4b5c6d",
  "eventType": "product_recall",
  "title": "Ceramic heater HX-200 recalled for overheating",
  "summary": "Voluntary recall of units made 2024-11 to 2025-02.",
  "region": "KR",
  "sourceUrl": "https://www.safetykorea.kr/recall/…",
  "sourcePublishedAt": "2026-10-18T00:00:00.000Z",
  "firstSeenAt": "2026-10-19T03:10:00.000Z",
  "lastVerifiedAt": "2026-10-22T03:10:00.000Z",
  "confidence": 85,
  "severity": 80,
  "sources": [
    {
      "key": "kr_safetykorea",
      "name": "SafetyKorea",
      "tier": "A",
      "url": "https://www.safetykorea.kr/…"
    }
  ],
  "officialActions": [
    "Stop using and contact the manufacturer"
  ]
}

GET /public/entities

List tracked items in the key's workspace

Required scope: read:entities

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/entities

Response (200)

JSON
{
  "items": [
    {
      "id": "3c0f…",
      "workspaceId": "9a1e…",
      "entityType": "software_version",
      "displayName": "Node.js",
      "manufacturer": null,
      "modelOrVersion": "18.20.0",
      "region": null,
      "identifiers": {
        "eolProduct": "nodejs"
      },
      "relationship": "used",
      "importance": 3,
      "aliases": [],
      "exclusions": [],
      "createdAt": "2026-10-22T05:00:00.000Z",
      "updatedAt": "2026-10-22T05:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST /public/entities

Track a new item

Matches against existing events start immediately; hint-driven sources (endoflife.date, OSV, NHTSA, GitHub) are queued for the next worker tick. Free plan: 25 items (409 `plan_limit`). `sourceUrls` pointing at private networks return 422 `ssrf_blocked`.

Required scope: write:entities

Request

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

Response (201)

JSON
{
  "entity": {
    "id": "3c0f…",
    "workspaceId": "9a1e…",
    "entityType": "software_version",
    "displayName": "Node.js",
    "manufacturer": null,
    "modelOrVersion": "18.20.0",
    "region": null,
    "identifiers": {
      "eolProduct": "nodejs"
    },
    "relationship": "used",
    "importance": 3,
    "aliases": [],
    "exclusions": [],
    "createdAt": "2026-10-22T05:00:00.000Z",
    "updatedAt": "2026-10-22T05:00:00.000Z"
  }
}

GET /public/alerts

List impact assessments (alerts) for the workspace

Latest assessment per event and item, newest first. `reasons` lists the rule codes behind each score.

Required scope: read:alerts

Parameters

limitqueryintegerPage size

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/alerts

Response (200)

JSON
{
  "items": [
    {
      "assessmentId": "5b2e…",
      "eventId": "7f1c…",
      "entityId": "3c0f…",
      "entityName": "Node.js",
      "eventType": "end_of_life",
      "title": "Node.js 18 (LTS) reached end of life on 2025-04-30",
      "summary": "Security fixes are no longer released.",
      "impactLevel": "critical",
      "matchType": "exact",
      "relevance": 60,
      "confidence": 85,
      "severity": 75,
      "reasons": {
        "relevance": [
          "exact_identifier",
          "relationship_owned"
        ],
        "confidence": [
          "official_source"
        ],
        "severity": [
          "eol_passed"
        ]
      },
      "sourceUrl": "https://endoflife.date/nodejs",
      "sourcePublishedAt": null,
      "firstSeenAt": "2026-10-20T05:07:00.000Z",
      "generatedAt": "2026-10-20T05:07:01.000Z"
    }
  ],
  "nextCursor": null
}

GET /public/webhooks

List webhooks

Required scope: manage:webhooks

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks

Response (200)

JSON
{
  "items": [
    {
      "id": "e4d1…",
      "url": "https://example.com/hooks/radar",
      "minLevel": "high",
      "enabled": true,
      "failures": 0,
      "lastDeliveryAt": null,
      "createdAt": "2026-10-22T05:00:00.000Z"
    }
  ],
  "nextCursor": null
}

POST /public/webhooks

Create a webhook

HTTPS only; private/internal hosts are rejected (422 `ssrf_blocked`). Up to 10 per workspace.

Required scope: manage:webhooks

Request

curl
curl -X POST -H "Authorization: Bearer rr_live_…" -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/radar","minLevel":"high"}' \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks

Response (201)

JSON
{
  "webhook": {
    "id": "e4d1…",
    "url": "https://example.com/hooks/radar",
    "minLevel": "high",
    "enabled": true,
    "failures": 0,
    "lastDeliveryAt": null,
    "createdAt": "2026-10-22T05:00:00.000Z"
  },
  "secret": "whsec_…"
}

DELETE /public/webhooks/{id}

Delete a webhook

Required scope: manage:webhooks

Parameters

idpath *string

Request

curl
curl -X DELETE -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks/ID

Response (200)

JSON
{
  "ok": true
}

GET /public/webhooks/{id}/deliveries

Recent deliveries (30-day log)

Required scope: manage:webhooks

Parameters

idpath *string

Request

curl
curl -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks/ID/deliveries

Response (200)

JSON
{
  "items": [
    {
      "id": "a0b1…",
      "eventType": "alert.created",
      "statusCode": 200,
      "durationMs": 182,
      "attempt": 1,
      "ok": true,
      "error": null,
      "replayOf": null,
      "payloadHash": "sha256 hex…",
      "createdAt": "2026-10-22T05:01:00.000Z"
    }
  ],
  "nextCursor": null
}

POST /public/webhooks/{id}/deliveries/{deliveryId}/replay

Replay a delivery

Re-sends the same body with a NEW timestamp and signature. 10 per minute.

Required scope: manage:webhooks

Parameters

idpath *string
deliveryIdpath *string

Request

curl
curl -X POST -H "Authorization: Bearer rr_live_…" \
  https://realityradar-7h6.pages.dev/api/v1/public/webhooks/ID/deliveries/DELIVERYID/replay

Response (200)

JSON
{
  "ok": true,
  "status": 200,
  "error": null,
  "deliveryId": "c2d3…"
}

Webhook events

EVENT alert.created

A new alert matched one of your items

Headers: `Content-Type: application/json`, `User-Agent: RealityRadar-Webhook/1.0`, `X-Radar-Signature: t=<unix>,v1=<hex>[,v1=<hex>]`. Compute HMAC-SHA256(secret, `${t}.${rawBody}`) and accept if it equals ANY v1 value and |now − t| ≤ 300 s. Two v1 values are sent for 24 h after a secret rotation. Respond 2xx within 10 s; non-2xx responses are retried and logged.

JSON
{
  "type": "alert.created",
  "alert": {
    "id": "…",
    "impactLevel": "critical",
    "matchType": "exact",
    "entityName": "Node.js"
  },
  "event": {
    "id": "…",
    "eventType": "end_of_life",
    "title": "Node.js 18 (LTS) reached end of life on 2025-04-30",
    "summary": "…",
    "sourceUrl": "https://endoflife.date/nodejs",
    "sourcePublishedAt": null,
    "firstSeenAt": "2026-10-20T05:07:00.000Z"
  }
}