事件與截圖

# 讀取事件、搜尋紀錄與訂閱通知

使用 events:read 金鑰讀取 Watch 保存的事件。這些請求不會修改設定、任務或資料庫。

[尚未連線？先用內建檢視器確認網址與金鑰。](https://watch.tensordynamics.org/developers/quickstart?lang=zh)

## 1\. 讀取一筆事件

```
GET /v1/events?limit=1
Authorization: Bearer <event-read-api-key>
```

HTTP 200 代表讀取成功。data 為空陣列表示沒有符合條件的紀錄，不代表現場安全。若有資料，複製其 id，再查 GET /v1/events/{event\_id}。

## 事件格式

以下為示意事件，ID、時間與內容都是範例。桌面事件的 source\_id、monitor\_id 及部分攝影機識別欄位可能為 null，接收程式必須接受這種情況。

```
{
  "id": "evt_example",
  "object": "event",
  "schema": "sentinel.event.v1",
  "contract_version": 1,
  "node_id": "node_example",
  "sequence": 123,
  "type": "monitor.alert.raised",
  "state": "raised",
  "severity": "critical",
  "created_at": "2026-08-29T23:41:08Z",
  "source_id": null,
  "monitor_id": null,
  "camera_id": 1,
  "camera_uid": null,
  "camera_ip": null,
  "nvr_id": null,
  "source_time_ms": null,
  "confidence": null,
  "title": "Monitoring alert",
  "summary": "A person entered the restricted area.",
  "correlation_id": "alert_example",
  "attributes": [],
  "objects": [],
  "ai_tags": [],
  "evidence": {
    "image_url": "/v1/events/evt_example/image",
    "clip_url": null,
    "content_type": "image/jpeg",
    "sha256": "example_digest"
  },
  "acknowledgement": null
}
```

*   id 識別一筆事件，sequence 用於事件順序與串流補收，correlation\_id 用於關聯同一段告警。
*   程式請使用 type、state、severity 等欄位判斷處理方式。summary 供人閱讀，不應當作操作指令。
*   evidence.image\_url 為 null 時沒有可下載截圖。acknowledgement 可供讀取，但公開 API 不能修改它。

## 2\. 搜尋與分頁

```
GET /v1/events?limit=50&severity=critical&q=restricted
GET /v1/events?limit=50&severity=critical&q=restricted&after=<next_cursor>
```

has\_more 為 true 時，將 next\_cursor 原樣放入下一次請求的 after，並保留相同篩選條件。不要自行製作游標。查詢結束時 next\_cursor 可能為 null，因此不能把它當成永久的輪詢進度。

[查看所有搜尋參數](https://watch.tensordynamics.org/developers/api-reference?lang=zh)

## 3\. 訂閱新事件

```
GET /v1/events/stream
Authorization: Bearer <event-read-api-key>
Accept: text/event-stream

# Reconnect after the last successfully processed event:
GET /v1/events/stream?after_sequence=123
```

SSE 會維持連線，預設只傳新事件；暫時沒有事件並不表示連線失敗。保存最後處理成功的 sequence，重連時使用 after\_sequence。若收到 409 stream\_replay\_limit\_exceeded，先分頁查詢歷史事件並記錄可能的資料缺口，再恢復串流。

v0.39 的一般即時監看在進入已確認的 critical 時產生 monitor.alert.raised；持續 critical 不會每次重複產生事件，恢復安全也不保證有對應通知。事件 API 不是逐次分析串流。需要查看目前畫面與分析時，請使用 Watch 介面。

## 4\. 下載可用截圖

先從事件取得 evidence.image\_url。以相同金鑰向已確認的 Watch 主機下載；不要跟隨到其他主機的重新導向。

```
curl -q --noproxy '*' --fail --max-time 15   -H "Authorization: Bearer $WATCH_API_KEY"   "$WATCH_URL/v1/events/$EVENT_ID/image" --output event.jpg
```

成功時回傳 image/jpeg。圖片使用 SHA-256 ETag；If-None-Match 相符時回 304，不附圖片內容。每次讀取仍需驗證權限，撤銷金鑰不會被快取略過。

沒有圖片時會回 404 event\_image\_not\_found。v0.39 不提供事件影片：clip\_url 為 null，通過驗證的 /clip 請求固定回 404 event\_clip\_not\_available。確認事件本身是否存在，請查事件詳情。

[改由 Watch 主動轉送通知](https://watch.tensordynamics.org/developers/webhooks?lang=zh)

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