# Updates Portal API

> URL: https://foura.ai/zh/docs/updates-portal/api
> Updated: 2026-11-05
> Index: https://foura.ai/llms.txt

Updates Portal 提供了轻量级的公开 JSON API，方便你从自己的系统轮询状态、获取更新日志条目、查看路线图以及排查已知问题。无需任何身份验证。该 API 仅提供英文文本内容；路径中的语言前缀会被忽略。

## 基础 URL

```
https://updates.foura.ai
```

## 服务状态

`GET /api/v1/status`

返回每个 FourA 服务的实时运行状态，以及当前活跃和最近发生的事件。服务端缓存 15 秒，因此高于该频率的轮询将返回相同的 payload。

```bash
curl https://updates.foura.ai/api/v1/status
```

```json
{
  "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`。请将其视为未知状态而非异常故障，并在下一次轮询时重试。

```python
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`

按时间倒序返回已发布的更新日志条目。

```bash
curl "https://updates.foura.ai/api/changelog?limit=20"
```

查询参数：

| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `page` | integer | 1 | 从 1 开始的页码 |
| `limit` | integer | 20 | 每页条目数（最大 50） |
| `category` | string | - | 筛选条件：`new`、`improved` 或 `fixed` |

```json
{
  "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`

返回所有已发布的路线图项目，按投票数排序，其次按创建时间排序。

```bash
curl https://updates.foura.ai/api/roadmap
```

```json
{
  "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](https://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"}`。

```bash
curl -X POST https://updates.foura.ai/api/roadmap/12/vote
```

```json
{ "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 支持团队跟踪的问题。

```bash
curl "https://updates.foura.ai/api/issues?tab=open"
```

查询参数：

| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `tab` | string | `open` | 活动问题使用 `open`，已解决/已关闭问题使用 `resolved` |

```json
{
  "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`](https://updates.foura.ai/rss) feed，而非 `/api/changelog`。

## 相关内容

- [服务状态](https://foura.ai/docs/updates-portal/status)：在浏览器中查看相同数据
- [更新日志](https://foura.ai/docs/updates-portal/changelog)：通过筛选和分页浏览条目
- [路线图](https://foura.ai/docs/updates-portal/roadmap)：在 UI 中为条目投票
- [已知问题](https://foura.ai/docs/updates-portal/issues)：查看处于开启和已解决状态的问题
- [更新门户](https://foura.ai/docs/updates-portal/overview)：分区概览
