Início rápido
Crie uma chave no app em Wire → Chaves de API e chame a API de qualquer lugar. As respostas são JSON e os horários, 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"])Autenticação
Envie a chave como token Bearer. Ela aparece uma única vez, é guardada só como hash, pode expirar em 30, 90 ou 365 dias e ser trocada com 24 horas de sobreposição.
Authorization: Bearer rr_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXEscopos
Cada chave tem só os escopos que você escolher. Uma solicitação fora deles retorna 403 insufficient_scope, então uma chave somente leitura nunca adiciona itens nem gerencia webhooks.
| Escopo | 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 |
Limites de uso
Chaves padrão permitem 60 solicitações por minuto e as ampliadas, 300. Um 429 significa esperar e tentar de novo; o uso por chave e endpoint aparece no Wire.
Paginação
Listagens retornam items e nextCursor. Devolva o cursor até ele ser null; cursores são opacos e estáveis durante a paginação.
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:
breakErros
Os erros têm um formato único com código estável. Repita 5xx e 429 com espera progressiva; um 4xx indica problema na solicitação.
{ "error": { "code": "insufficient_scope", "message": "This key lacks the \"write:entities\" scope" } }invalid_api_key | 401 | Chave ausente, malformada ou revogada |
api_key_expired | 401 | A chave passou da validade ou do período de troca |
insufficient_scope | 403 | A chave não tem o escopo exigido por este endpoint |
not_found | 404 | Não encontrado ou não visível para este espaço |
plan_limit | 409 | Limite de itens do plano gratuito atingido |
ssrf_blocked | 422 | A URL aponta para um endereço privado ou interno |
rate_limited | 429 | Solicitações demais — tente após a janela |
Webhooks
Webhooks enviam por POST um evento JSON quando é criado um alerta do seu nível ou acima. O registro de entregas guarda 30 dias com status, latência e reenvio com um clique.
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 assinaturas
Calcule o HMAC-SHA256 de t, um ponto e o corpo bruto com seu segredo, compare em tempo constante com qualquer v1 e rejeite horários com mais de cinco minutos. Após trocar o segredo, chegam dois v1 por 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/replayDependências e OSV
Acompanhe pacotes com um purl como pkg:npm/lodash e uma versão exata. O Reality Radar consulta o OSV.dev e marca a correspondência como exata quando sua versão aparece como afetada. Envie lockfiles ou SBOMs no app, em 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/entitiesGlossário
Termos que você verá nas respostas.
- Signal (sinal)
- Uma mudança detectada em fonte oficial, com evidências e horários.
- Beacon
- Uma fonte de dados. Nível A é um órgão regulador ou fabricante oficial; nível B, um banco de dados curado.
- Tipo de correspondência
- exact, strong, probable ou weak — o quanto temos certeza de que o evento se refere ao seu item. Só exact e strong são apresentados como certos.
- Relevância, confiança, gravidade
- Três pontuações de 0 a 100 calculadas separadamente: se diz respeito a você, quão confiável é a evidência e quão grave é a mudança.
- purl
- Package URL, como pkg:npm/lodash, o identificador padrão usado na correspondência com o OSV.
- Registro de evidências
- Uma cadeia de hashes à prova de adulteração com cada evidência guardada, verificável por qualquer pessoa.