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 格式的变更日志,请使用 /rss feed,而非 /api/changelog。
更新于: 2026年11月5日