API 參考

v0.39 唯讀事件 API

用 AI 閱讀

本頁完整列出客戶可用的事件查詢、串流與證據讀取介面。使用 Watch 顯示的 API 網址與 events:read 金鑰；設定和任務仍在 Watch 介面操作。

完整事件端點

GET /v1/events
GET /v1/events/stream
GET /v1/events/{event_id}
GET /v1/events/{event_id}/image
GET /v1/events/{event_id}/clip

/events：查詢與分頁。HTTP 200 且 data 為空，表示目前沒有符合條件的紀錄。
/events/stream：以 SSE 接收新事件，回應為 text/event-stream。預設不補送歷史。
/events/{event_id}：取得一筆事件。請使用列表回傳的真實 ID；不存在時回傳 404。
/image：下載保存的 JPEG 截圖。沒有可用圖片時回傳 404 event_image_not_found。
/clip：v0.39 保留這個路徑，但不提供事件影片。通過驗證後固定回傳 404 event_clip_not_available，clip_url 為 null。

參數	用途
limit / after	每頁 1–500 筆，預設 100；after 使用上一頁的 next_cursor。
type / severity / state	依事件類型、嚴重度與狀態篩選；同一參數可重複。
source_id / monitor_id	依事件已有的關聯 ID 篩選。桌面事件可能沒有這些關聯。
nvr_id / camera_uid / camera_ip	依已有的攝影機識別資料篩選；資料未提供時，篩選不會補上它。
ai_tag	依分析標籤篩選，可重複。
acknowledged	依既有確認狀態篩選。公開 API 不提供寫入確認狀態的操作。
created_after / created_before	RFC 3339 時間範圍，包含起點、不含終點。
q	1–200 字元的文字搜尋。

severity 接受 safe、suspicious、critical；state 接受 raised、updated、cleared。這些是查詢值，不代表每種監看模式都會產生所有狀態。v0.39 即時告警的實際行為請見事件指南。

GET /healthz
GET /readyz
GET /v1/openapi.json
GET /v1/docs

/healthz 的 200 表示服務有回應。/readyz 也能透過 LAN 讀取，但桌面版可能回 503；請以 /healthz 與帶金鑰的事件查詢確認桌面整合，不要把 /readyz 當成唯一判斷。桌面 LAN 另提供 /viewer/，但不提供 ReDoc。

你的 Watch 節點網址

只用來產生下方連結；此公開頁面不會要求、傳送或保存 API key。

請輸入不含帳號密碼的 http:// 或 https:// URL。

這份文件只包含公開的唯讀事件介面。產生用戶端後，請把服務網址設為 Watch 提供的實際網址；不要將 API 金鑰傳到本文件網站。

Authorization: Bearer <event-read-api-key>
X-Request-ID: req_optional_correlation

公開事件 API 不接受設定變更、建立事件、確認事件或其他寫入操作。桌面事件轉送請從 Watch 的設定介面建立；它不是公開 API 的寫入功能。