功能

代理回報

代理和應用程式可以回報使用者剛剛經歷的等候。回報用於補足沒有即時公布等候的地點，一律標示為回報，且絕不接受急診室或緊急照護的回報。

這是什麼

POST /v1/places/{id}/reports 與 report_wait 工具會儲存某人實際經歷的等候。回報與公布的等候分開存放：它們有自己的層級 agent，絕不與官方或地點公布的數字混在一起。

如何回報

在到訪後立即傳送使用者等候的分鐘數。回報需要 API 金鑰，並算作一次呼叫。

wait_min：分鐘，0 到 600。必填。
observed_at：使用者經歷等候的時間，含時區偏移的 ISO 8601，須在過去 2 小時內。預設為現在。
kind：仍在排隊時用 in_line（到目前為止的等候），剛結束的完整等候用 done。

curl -X POST "https://api.waity.ai/v1/places/pl_nvk0wkb3ps/reports" \
  -H "X-Api-Key: $WAITY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wait_min":25,"kind":"done"}'

已儲存的回報會回傳 201，附上其 report.id 與 shown。未顯示時，reason 說明原因：needs_more_reports、official_wait、closed、too_old 或 out_of_range。

MCP 工具

report_wait 接受相同的欄位，外加地點的 id。它是唯一會寫入的 MCP 工具，因此其註解表明它不是唯讀的。

回報何時顯示

只有當地點沒有可用的官方或地點公布的等候，且沒有關門時才會顯示。即時公布的等候一律優先；回報會留在歷史中。
只有當過去 45 分鐘內至少有 2 個不同的人回報或確認，或有一位可信的回報者（其先前回報已被他人確認）回報時才會顯示。
顯示的等候是每個人最新回報的中位數。當時間窗內剩下的人少於 2 個時，就不再顯示。

如何標示

回報的等候帶有 now.tier: "agent"、now.basis: "reported" 與 now.source.name: "people"，並有自己的 now.source.short。其摘要說明這是由人回報的（「reported by 2 people」），而不是地點公布的。

回報的分鐘數絕不與公布的分鐘數比較：同時含有兩者的清單會說明這一點，instead 也絕不會把其中一個說成比另一個短。

絕不用於急診室或緊急照護

對這些地點的回報會以 422 reports_not_accepted 被拒絕，且不儲存任何內容。

限制與隱私

沒有金鑰的呼叫會收到 401 key_required；不計入次數。
每個回報者在每個地點每 30 分鐘一筆回報（429 report_too_soon，附 Retry-After）。
每個回報者每天 200 筆回報（429 report_limit，直到 UTC 午夜）。
回報只儲存金鑰的 id。請勿傳送姓名、電話號碼或其他個人資料。

回報合作夥伴（例如透過一個金鑰替許多人回報的簡訊服務）可以傳送 reporter：每個人的穩定單向雜湊，絕不是原始電話號碼或電子郵件。合作夥伴金鑰由 Waity 設定；其他金鑰的 reporter 會被忽略。

在歷史中

回報以 tier=agent 出現在歷史中：raw 中列出每筆回報，按小時或按天的數字與公布的等候計算方式相同。