API 參考

# v0.39 唯讀事件 API

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

[第一次使用？先用事件檢視器確認連線。](https://watch.tensordynamics.org/developers/quickstart?lang=zh)

## 完整事件端點

```
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 即時告警的實際行為請見事件指南。

[事件格式與串流步驟](https://watch.tensordynamics.org/developers/events?lang=zh)

## 連線與本機文件

```
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。

連線檢查 ↗Swagger UI ↗OpenAPI JSON ↗

## 下載公開 OpenAPI

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

[下載 OpenAPI JSON](https://watch.tensordynamics.org/api/v1/openapi.json)

## 請求標頭

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

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

---
Source: https://watch.tensordynamics.org/developers/api-reference?lang=zh
More Watch guides: https://watch.tensordynamics.org/llms.txt