功能

代理报告

代理和应用可以报告用户刚刚经历的等待。报告用于填补没有实时公布等待的地点，始终标注为报告，且绝不接受急诊室或紧急护理的报告。

这是什么

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 中列出每份报告，按小时或按天的数字与公布的等待计算方式相同。