Inicio rápido
Crea una clave en la app en Wire → Claves de API y llama a la API desde cualquier lugar. Las respuestas son JSON y las horas, ISO-8601 UTC.
curl -H "Authorization: Bearer rr_live_…" \
https://realityradar-7h6.pages.dev/api/v1/public/alerts?limit=5const 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());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"])Autenticación
Envía la clave como token Bearer. Se muestra una sola vez, se guarda solo como hash, puede caducar a los 30, 90 o 365 días y rotarse con 24 horas de solapamiento.
Authorization: Bearer rr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXPermisos
Cada clave lleva solo los permisos que elijas. Una solicitud fuera de ellos devuelve 403 insufficient_scope, así que una clave de solo lectura nunca puede añadir elementos ni gestionar webhooks.
| Permiso | Endpoints |
|---|---|
read:signals | GET /public/eventsGET /public/events/{id} |
read:entities | GET /public/entities |
write:entities | POST /public/entities |
read:alerts | GET /public/alerts |
manage:webhooks | GET /public/webhooksPOST /public/webhooksDELETE /public/webhooks/{id}GET /public/webhooks/{id}/deliveriesPOST /public/webhooks/{id}/deliveries/{deliveryId}/replay |
Límites de uso
Las claves estándar permiten 60 solicitudes por minuto y las ampliadas 300. Un 429 significa esperar y reintentar; el uso por clave y endpoint se ve en Wire.
Paginación
Los listados devuelven items y nextCursor. Envía el cursor de vuelta hasta que sea null; los cursores son opacos y estables mientras paginas.
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:
breakErrores
Los errores comparten un formato con un código estable. Reintenta 5xx y 429 con espera progresiva; un 4xx indica un problema en la solicitud.
{ "error": { "code": "insufficient_scope", "message": "This key lacks the \"write:entities\" scope" } }invalid_api_key | 401 | Clave ausente, mal formada o revocada |
api_key_expired | 401 | La clave superó su caducidad o el periodo de rotación |
insufficient_scope | 403 | La clave no tiene el permiso que requiere este endpoint |
not_found | 404 | No existe o no es visible para este espacio |
plan_limit | 409 | Se alcanzó el límite de elementos del plan gratuito |
ssrf_blocked | 422 | La URL apunta a una dirección privada o interna |
rate_limited | 429 | Demasiadas solicitudes: reintenta tras la ventana |
Webhooks
Los webhooks envían por POST un evento JSON cuando se crea una alerta de tu nivel o superior. El registro de entregas guarda 30 días con estado, latencia y reenvío con un clic.
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":{…}}Verificar firmas
Calcula HMAC-SHA256 de t, un punto y el cuerpo sin procesar con tu secreto, compáralo en tiempo constante con cualquier v1 y rechaza marcas de tiempo de más de cinco minutos. Tras rotar el secreto llegan dos v1 durante 24 horas.
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)));
}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)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
}# 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/replayDependencias y OSV
Sigue paquetes con un purl como pkg:npm/lodash y una versión exacta. Reality Radar consulta OSV.dev y marca la coincidencia como exacta si tu versión figura como afectada. Sube lockfiles o SBOM en la app, en Importar.
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/entitiesGlosario
Términos que verás en las respuestas.
- Signal (señal)
- Un cambio detectado en una fuente oficial, con evidencia y marcas de tiempo.
- Beacon (baliza)
- Una fuente de datos. Nivel A es un regulador o fabricante oficial; nivel B, una base de datos curada.
- Tipo de coincidencia
- exact, strong, probable o weak: qué tan seguros estamos de que el evento trata de tu elemento. Solo exact y strong se presentan como seguros.
- Relevancia, confianza, gravedad
- Tres puntuaciones de 0 a 100 calculadas por separado: si te afecta, qué tan fiable es la evidencia y qué tan grave es el cambio.
- purl
- Package URL, p. ej. pkg:npm/lodash, el identificador estándar que se usa para cruzar con OSV.
- Registro de evidencias
- Una cadena de hashes a prueba de manipulaciones con cada evidencia guardada, verificable por cualquiera.