公开 API
/api/v1 是面向替代前端、公开面板、Canvas 主题与服务端集成的稳定只读接口。读取不需要 Token，写入能力不对第三方开放。文档对应 Worker 1.1.93，实际能力以目标部署的 Manifest 为准。
端点清单
| 方法 | 路径 | 用途 | 默认速率限制 |
|---|---|---|---|
GET | /api/v1 | 版本、能力与端点发现 | 公共读取策略 |
GET | /api/v1/manifest | Manifest 等价别名 | 公共读取策略 |
GET | /api/v1/status | 目标、当前状态、汇总与遥测 | 120 次/分钟/IP |
GET | /api/v1/checks | 单个目标的可用性历史 | 120 次/分钟/IP |
GET | /api/v1/metrics | 单个 Agent 的指标历史 | 30 次/分钟/IP |
GET | /api/v1/pings | Agent TCP Ping 历史 | 30 次/分钟/IP |
GET | /api/v1/latency | 外部 Latency Agent 历史 | 60 次/分钟/IP |
限制是当前生产默认值，后续版本可能调整。客户端不应把它们当成并发目标；状态页按缓存周期刷新即可。
所有路由还受 Worker 全局最佳努力限流保护。限流计数不可用时公开读取可能继续提供服务；客户端仍应按 429 退避，不依赖某次请求没有被限流。
基本请求
export API_BASE='https://YOUR-API'
curl -fsSL "$API_BASE/api/v1"
curl -fsSL "$API_BASE/api/v1/status?days=30&lite=1"const response = await fetch(`${apiBase}/api/v1/status?days=30&lite=1`, {
method: 'GET',
credentials: 'omit',
headers: { accept: 'application/json' },
})
if (!response.ok) throw new Error(`HTTP ${response.status}`)
const status = await response.json()CORS
服务端集成不受浏览器 CORS 限制。浏览器替代前端必须把精确 Origin 加入 Worker 的 DEVELOPER_API_ORIGINS：
DEVELOPER_API_ORIGINS = "https://status.example.com,http://localhost:5173"规则：只接受完整 Origin，不含路径与尾部 /；生产必须 HTTPS；HTTP 只允许 localhost 开发地址；* 被忽略；该变量只影响 /api/v1，不开放 Admin 或 Agent 写接口。Worker 自身配置的正式站点 Origin 自动加入允许集合。未命中 allowlist 时响应可能仍是 HTTP 200，但 Access-Control-Allow-Origin 不回显请求 Origin，浏览器会阻止脚本读取。
响应约定
成功响应包含 ok: true；错误通常包含 ok: false 与 error。客户端必须同时检查 HTTP 状态与 JSON ok（Latency 兼容错误当前可能使用 HTTP 200）。v1 响应以 X-NIE-SLA-API-Version: v1 标识版本，并继续发送旧 X-NStatus-API-Version 兼容头。缓存响应同样优先使用 X-NIE-SLA-Cache / X-NIE-SLA-Source，旧 X-NStatus-* 头在 v1 内保留，不改变数据语义。
缓存与刷新
各端点可能返回 Cache-Control，状态与历史接口可能命中 Cloudflare Cache API。尊重缓存头，不要高频轮询制造无意义请求。建议公开面板：当前状态每 20–60 秒刷新；图表仅在打开详情或切换时间范围时请求；页面隐藏时暂停轮询；网络恢复后加随机延迟。
稳定性规则
v1 中服务端可以增加可选字段、数组成员与能力标识，但不会无公告删除或重命名既有字段。客户端必须忽略未知字段，并处理 null、空数组、无历史与暂时过期的数据源。