Events & images
結構化事件，獨立的二進位證據
Event 是可依賴的機器輸出：穩定 ID、類型、生命週期、嚴重度、信心、Source/Monitor 關聯與結構化 attributes。摘要只供人閱讀。
生命週期
monitor.alert.raised → monitor.alert.updated → monitor.alert.cleared同一個實際事件保留穩定 Event identity 與單調 sequence。消費方不應把每次 update 當成新的 Incident，也不應因 cleared 自動結束人的工作項目。
事件形狀
{
"id": "evt_01...",
"type": "monitor.alert.raised",
"state": "raised",
"severity": "critical",
"confidence": 0.93,
"source_id": "src_01...",
"monitor_id": "mon_01...",
"created_at": "2026-08-29T23:41:08Z",
"summary": "A person entered the loading area after hours.",
"attributes": [],
"evidence": {
"image_url": "/v1/events/evt_01.../image",
"clip_url": null,
"content_type": "image/jpeg",
"sha256": "..."
}
}以上是概念 shape；精確欄位以目前 /v1/openapi.json 為準。無論 shape 細節，正常 Event 與 Webhook 都使用 image_url，不內嵌 Base64。
查詢與串流
GET /v1/events?limit=50
GET /v1/events/{event_id}
GET /v1/events/stream
GET /v1/analyses?monitor_id=mon_01...&limit=100
GET /v1/analyses/stream?source_id=src_01...GET /v1/events 是持久化事件／警告資料庫，列表使用穩定 cursor；它保存可查詢的 lifecycle Event。GET /v1/events/stream 是即時警報／錯誤 SSE 輸出，signed Webhook 則是跨系統的可靠警報／錯誤輸出。普通推論文字不寫入 Event ledger：GET /v1/analyses 取得每個 Monitor 最新結果，/v1/analyses/stream 以 SSE 取得每次結果；兩者都需要 events:read。
下載圖片
curl --fail http://localhost:8000/v1/events/$EVENT_ID/image \
-H "Authorization: Bearer $SENTINEL_API_KEY" \
--output event.jpg- Content-Type: image/jpeg
- Cache-Control: private, no-cache · Vary: Authorization
- 強 SHA-256 ETag；If-None-Match 命中回 304 且無 body。
- 與 Event JSON 相同，都需要 events:read Bearer 權限。
- Private cache 每次都要重新驗證，所以撤銷 key 或更改 scope 會在重用 cached bytes 前生效。
Source image 是 no-store 的目前畫面；Event image 是 bytes 不可變但 authorization 必須 revalidate 的歷史證據。不要互換兩者的快取、稽核或保存語意。