Updates Portal API
Updates Portal 提供了轻量级的公开 JSON API,方便你从自己的系统轮询状态、获取更新日志条目、查看路线图以及排查已知问题。无需任何身份验证。该 API 仅提供英文文本内容;路径中的语言前缀会被忽略。
基础 URL
https://updates.foura.ai
服务状态
GET /api/v1/status
返回每个 FourA 服务的实时运行状态,以及当前活跃和最近发生的事件。服务端缓存 15 秒,因此高于该频率的轮询将返回相同的 payload。
curl https://updates.foura.ai/api/v1/status
{
"overall": "operational",
"updated_at": "2026-05-19T12:00:00.000Z",
"services": [
{
"slug": "api-gateway",
"name": "API Gateway",
"description": "...",
"status": "operational",
"daily": [
{ "date": "2026-05-19", "status": "operational", "major_outage_minutes": 0, "partial_outage_minutes": 0, "degraded_minutes": 0, "internal_degraded_minutes": 0 }
]
}
],
"active_incidents": [],
"recent_incidents": [
{ "id": 12, "service_slug": "api-gateway", "service_name": "API Gateway", "impact": "minor", "title": "API Gateway: Degraded Performance", "status": "resolved", "started_at": "...", "resolved_at": "...", "duration_seconds": 30 }
]
}
| 顶级字段 | 类型 | 描述 |
|---|---|---|
overall |
string | 若所有服务均正常则为 operational,否则为某个具体的服务状态值 |
updated_at |
string | 状态数据生成的时间,带 Z 后缀的 ISO 8601 格式 |
services |
array | 每个监控服务对应一项,包含 slug、name、description、当前 status 以及 daily 历史记录(最多 90 天) |
active_incidents |
array | 当前未解决的事件 |
recent_incidents |
array | 过去 14 天内已解决的事件,每项包含 id、service_slug、service_name、impact、title、status、started_at、resolved_at 和 duration_seconds |
服务 status 取值:operational、degraded、partial_outage、major_outage、maintenance。对于无记录数据的日期,daily 项也可以显示为 no_data。internal_degraded_minutes 统计对客户无影响的时间。
事件 impact 取值:minor(性能降级)、major(部分中断)、critical(服务中断)。
轮询模式
使用此 endpoint 将 FourA 状态接入您自己的仪表板或寻呼报警系统。
当无法获取状态数据时,endpoint 会返回带有 {"error": "Monitor unreachable"} 的 502。请将其视为未知状态而非异常故障,并在下一次轮询时重试。
import requests
def check_foura():
r = requests.get("https://updates.foura.ai/api/v1/status", timeout=5)
r.raise_for_status() # raises on the 502 "Monitor unreachable" answer: retry next poll
data = r.json()
if data["overall"] != "operational":
# Page on-call, post to Slack, flip a feature flag, etc.
for svc in data["services"]:
if svc["status"] != "operational":
print(f"{svc['name']}: {svc['status']}")
return data
旧版 GET /api/status 返回 410 Gone 并将调用方引导至此处。
更新日志
GET /api/changelog
按时间倒序返回已发布的更新日志条目。
curl "https://updates.foura.ai/api/changelog?limit=20"
查询参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
page |
integer | 1 | 从 1 开始的页码 |
limit |
integer | 20 | 每页条目数(最大 50) |
category |
string | - | 筛选条件:new、improved 或 fixed |
{
"entries": [
{
"id": 42,
"title": "...",
"body": "Markdown body",
"category": "new",
"tags": "[\"api\",\"dashboard\"]",
"published": 1,
"published_at": "2026-05-19T12:00:00Z",
"created_at": "2026-05-19 11:42:08",
"updated_at": "2026-05-19 11:44:31"
}
],
"total": 137,
"page": 1,
"limit": 20
}
| 字段 | 类型 | 说明 |
|---|---|---|
id |
integer | 条目 ID |
title |
string | 条目标题 |
body |
string | Markdown 正文 |
category |
string | new、improved 或 fixed |
tags |
string | 编码为字符串的 JSON 数组。使用前请先解析: json.loads(entry["tags"])。 |
published |
integer | 此处始终为 1。该 endpoint 仅返回已发布的条目。 |
published_at |
string | 带 Z 后缀的 ISO 8601 |
created_at |
string | YYYY-MM-DD HH:MM:SS, UTC, 无时区标识 |
updated_at |
string | 格式与 created_at 相同 |
这两种时间戳格式是有意设计为不同的: published_at 是发布编辑日期并包含时区,而 created_at 和 updated_at 是存储时间戳。两者均为 UTC。如果解析器假设三者使用同一种格式,解析另外两种格式时将会报错。
RSS
完整的更新日志(最新的 30 个条目)也会以 RSS 形式发布于:
https://updates.foura.ai/rss
可在 Feedly、Miniflux、Thunderbird 或任何阅读器中订阅。Feed 内容与更新日志内容一致,包括渲染为 HTML 的 Markdown。
路线图
GET /api/roadmap
返回所有已发布的路线图项目,按投票数排序,其次按创建时间排序。
curl https://updates.foura.ai/api/roadmap
{
"items": [
{
"id": 12,
"title": "...",
"description": "...",
"status": "planned",
"category": "developer-experience",
"votes": 23,
"target_date": "Q3 2026",
"completed_at": null,
"created_at": "2026-03-30 09:32:47"
}
]
}
项 status 的值:planned、in_progress、done、cancelled。updates.foura.ai/roadmap 处的看板仅渲染三列,因此设置为 cancelled 的项会通过此 endpoint 返回,但绝不会出现在页面上。
category 是小写 slug,而不是页面上显示的标签。当前使用的 slug 包括:api、infrastructure、developer-experience、dashboard、billing、analytics、authentication。该列表可能随时扩充,因为新项可能会引入新的 slug。
target_date 是自定义文本("Q3 2026"),不是日期。在项发布之前,completed_at 为 null;发布后则为带有 Z 后缀的 ISO 8601 格式(2026-09-01T10:15:30.000Z),与 changelog 条目的 published_at 格式相同。created_at 使用 UTC 的 YYYY-MM-DD HH:MM:SS。同一个对象内存在这两种不同的格式,因此请分别解析各个字段。
投票
POST /api/roadmap/:id/vote
切换单个路线图项的投票状态。投票为匿名机制,绑定调用方的 IP 以及其 User-Agent 的前 50 个字符。再次调用将取消投票。未知或未发布的项将返回 404 {"error": "Not found"}。
curl -X POST https://updates.foura.ai/api/roadmap/12/vote
{ "votes": 24, "voted": true }
voted 报告调用后的状态:如果添加了投票,则为 true;如果移除了投票,则为 false。
路线图 endpoint(GET /api/roadmap 以及当前 endpoint)对每个源 IP 限制为每分钟 30 个 request。超出后将返回 HTTP 429 及 {"error": "Too many votes, slow down"}。每个路线图 response 都包含 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset(Unix 秒级时间戳),方便你在达到 rate limit 前放慢请求频率。
已知问题
GET /api/issues
返回由 FourA 支持团队跟踪的问题。
curl "https://updates.foura.ai/api/issues?tab=open"
查询参数:
| 参数 | 类型 | 默认值 | 描述 |
|---|---|---|---|
tab |
string | open |
活动问题使用 open,已解决/已关闭问题使用 resolved |
{
"issues": [
{
"id": 5,
"title": "...",
"body": "Markdown description",
"severity": "medium",
"status": "investigating",
"service_id": 3,
"resolution": "",
"opened_at": "2026-05-18T09:00:00Z",
"resolved_at": null,
"service_name": "API"
}
]
}
| 字段 | 类型 | 说明 |
|---|---|---|
id |
integer | 问题 ID |
title |
string | 简短摘要 |
body |
string | Markdown 格式描述 |
severity |
string | low、medium、high 或 critical |
status |
string | open、investigating、resolved 或 closed |
service_id |
integer or null | 受影响服务的数字 ID。未关联到具体服务时为 null。 |
service_name |
string or null | 已解析的服务显示名称。直接读取该字段,无需自行映射 service_id。 |
resolution |
string | 修复方案。问题处于开启状态时为空字符串。 |
opened_at |
string | 带有 Z 后缀的 ISO 8601 格式 |
resolved_at |
string or null | 带有 Z 后缀的 ISO 8601 格式,处于开启状态时为 null |
service_id 为数字外键,并非状态页面上显示的 slug。请通过 service_name 将问题与服务进行匹配。
问题响应载荷采用固定列列表,且不包含修改时间戳。可通过 opened_at 和 resolved_at 对问题进行排序或判断时效。在三个公开集合中,仅变更日志条目返回 updated_at。路线图条目还会额外返回 created_at,而问题条目两者均不返回。
resolved 选项卡最多返回最近解决的 30 个问题。open 选项卡则返回所有问题。
注意事项
- 所有 endpoint 均为公开接口,无需 API key。路线图 endpoint 限制每个源 IP 每分钟 30 次 request;其他接口目前均无独立 rate limit,因此轮询状态的频率不应高于其 15 秒缓存周期。
- 响应为 HTTPS 上的 JSON 数据。路线图和问题接口不支持分页参数。唯一的上限是问题接口中的
?tab=resolved,该接口固定返回 30 行数据。 - 如需纯文本或原始 HTML 格式的变更日志,请使用
/rssfeed,而非/api/changelog。