# API Portal cập nhật

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

Updates Portal cung cấp một JSON API công khai thu gọn để bạn có thể truy vấn trạng thái, nạp các mục changelog, theo dõi roadmap và kiểm tra các sự cố đã biết từ hệ thống của riêng mình. Không yêu cầu xác thực. API chỉ phân phát văn bản tiếng Anh; tiền tố ngôn ngữ trong đường dẫn sẽ bị bỏ qua.

## Base URL

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

## Trạng thái dịch vụ

`GET /api/v1/status`

Trả về trạng thái hoạt động trực tiếp của từng dịch vụ FourA, cùng với các sự cố đang diễn ra và gần đây. Được lưu cache phía máy chủ trong 15 giây, vì vậy gửi yêu cầu thăm dò thường xuyên hơn khoảng thời gian này sẽ trả về cùng một 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 }
  ]
}
```

| Trường cấp cao nhất | Kiểu | Mô tả |
|-----------------|------|-------------|
| `overall` | string | `operational` nếu mọi dịch vụ đều bình thường, nếu không sẽ là một trong các giá trị trạng thái dịch vụ |
| `updated_at` | string | Thời điểm dữ liệu trạng thái được tạo, định dạng ISO 8601 kèm hậu tố `Z` |
| `services` | array | Một mục cho mỗi dịch vụ được theo dõi với `slug`, `name`, `description`, `status` hiện tại và lịch sử `daily` (tối đa 90 ngày) |
| `active_incidents` | array | Các sự cố hiện đang mở |
| `recent_incidents` | array | Các sự cố đã giải quyết trong 14 ngày qua, mỗi sự cố gồm `id`, `service_slug`, `service_name`, `impact`, `title`, `status`, `started_at`, `resolved_at` và `duration_seconds` |

Các giá trị `status` của dịch vụ: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`. Một mục `daily` cũng có thể mang giá trị `no_data`, áp dụng cho ngày không có dữ liệu được ghi nhận. `internal_degraded_minutes` tính khoảng thời gian không ảnh hưởng đến khách hàng.

Các giá trị `impact` của sự cố: `minor` (hiệu năng suy giảm), `major` (gián đoạn một phần), `critical` (gián đoạn dịch vụ).

### Cơ chế polling

Sử dụng endpoint này để tích hợp trạng thái FourA vào trang tổng quan hoặc hệ thống phân trang (paging) của bạn.

Khi không thể lấy dữ liệu trạng thái, endpoint sẽ trả về `502` kèm `{"error": "Monitor unreachable"}`. Hãy xem đó là trạng thái chưa xác định thay vì trạng thái lỗi, và thử lại ở chu kỳ poll tiếp theo.

```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` cũ trả về `410 Gone` và điều hướng người gọi đến đây.

## Nhật ký thay đổi

`GET /api/changelog`

Trả về các mục nhật ký thay đổi đã xuất bản theo thứ tự thời gian đảo ngược.

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

Các query parameter:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Số trang (bắt đầu từ 1) |
| `limit` | integer | 20 | Số mục trên mỗi trang (tối đa 50) |
| `category` | string | - | Lọc theo `new`, `improved`, hoặc `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
}
```

| Trường | Kiểu dữ liệu | Mô tả |
|-------|------|-------------|
| `id` | integer | ID mục nhập |
| `title` | string | Tiêu đề mục nhập |
| `body` | string | Nội dung Markdown |
| `category` | string | `new`, `improved`, hoặc `fixed` |
| `tags` | string | Một mảng JSON **được mã hóa dưới dạng chuỗi**. Hãy parse chuỗi này trước khi dùng: `json.loads(entry["tags"])`. |
| `published` | integer | Luôn là `1` ở đây. Endpoint này chỉ trả về các mục nhập đã xuất bản. |
| `published_at` | string | ISO 8601 kèm hậu tố `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, không có ký hiệu múi giờ |
| `updated_at` | string | Định dạng tương tự như `created_at` |

Hai định dạng mốc thời gian này khác nhau là có chủ đích: `published_at` là ngày biên tập và có kèm múi giờ, trong khi `created_at` và `updated_at` là mốc thời gian lưu trữ. Cả hai đều là UTC. Trình phân tích cú pháp mặc định một định dạng duy nhất cho cả ba trường sẽ gặp lỗi với hai trường còn lại.

### RSS

Toàn bộ nhật ký thay đổi (30 mục nhập gần nhất) cũng được xuất bản dưới dạng RSS tại:

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

Đăng ký trong Feedly, Miniflux, Thunderbird hoặc bất kỳ trình đọc nào. Nội dung feed khớp với nội dung changelog, bao gồm cả markdown được render sang HTML.

## Lộ trình phát triển

`GET /api/roadmap`

Trả về mọi mục roadmap đã xuất bản, sắp xếp theo số lượt bình chọn rồi đến thời gian tạo.

```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"
    }
  ]
}
```

Các giá trị của `status` cho mục: `planned`, `in_progress`, `done`, `cancelled`. Bảng tại [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) hiển thị ba cột, vì vậy một mục được đặt thành `cancelled` sẽ đến với bạn qua endpoint này và không bao giờ xuất hiện trên trang.

`category` là slug chữ thường, không phải nhãn mà trang in ra. Các slug đang được sử dụng hiện nay: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Hãy xem danh sách này là mở, vì một mục mới có thể bổ sung một slug mới.

`target_date` là văn bản tự do (`"Q3 2026"`), không phải ngày tháng. `completed_at` là `null` cho đến khi mục được phát hành, sau đó là định dạng ISO 8601 với hậu tố `Z` (`2026-09-01T10:15:30.000Z`), cùng định dạng với `published_at` của mục nhật ký thay đổi. `created_at` sử dụng `YYYY-MM-DD HH:MM:SS` theo UTC. Hai định dạng này khác nhau trong cùng một đối tượng, vì vậy hãy phân tích cú pháp từng trường riêng biệt.

### Bỏ phiếu

`POST /api/roadmap/:id/vote`

Bật hoặc tắt bình chọn cho một mục lộ trình duy nhất. Bình chọn là ẩn danh và được liên kết với IP của bên gọi cùng 50 ký tự đầu tiên của User-Agent. Gọi lại lần nữa sẽ xóa bình chọn. Một mục không xác định hoặc chưa được xuất bản sẽ phản hồi `404 {"error": "Not found"}`.

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

```json
{ "votes": 24, "voted": true }
```

`voted` báo cáo trạng thái sau lệnh gọi: `true` nếu vote của bạn đã được thêm, `false` nếu vote đã bị xóa.

Các endpoint roadmap, `GET /api/roadmap` và endpoint này, bị giới hạn 30 request mỗi phút cho từng IP nguồn. Vượt quá mức đó, kết quả trả về là HTTP `429` cùng `{"error": "Too many votes, slow down"}`. Mọi response của roadmap đều chứa `X-RateLimit-Limit`, `X-RateLimit-Remaining`, và `X-RateLimit-Reset` (Unix timestamp tính bằng giây), giúp bạn có thể giảm tốc độ trước khi chạm giới hạn.

## Sự cố đã biết

`GET /api/issues`

Trả về các sự cố được bộ phận hỗ trợ FourA theo dõi.

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

Query parameters:

| Parameter | Type | Mặc định | Mô tả |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` cho các sự cố đang hoạt động, `resolved` cho các sự cố đã giải quyết/đã đóng |

```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"
    }
  ]
}
```

| Trường | Loại dữ liệu | Mô tả |
|-------|------|-------------|
| `id` | integer | ID sự cố |
| `title` | string | Tóm tắt ngắn gọn |
| `body` | string | Mô tả định dạng Markdown |
| `severity` | string | `low`, `medium`, `high`, hoặc `critical` |
| `status` | string | `open`, `investigating`, `resolved`, hoặc `closed` |
| `service_id` | integer hoặc null | ID dạng số của dịch vụ bị ảnh hưởng. `null` khi sự cố không liên kết với dịch vụ nào. |
| `service_name` | string hoặc null | Tên hiển thị của dịch vụ, đã được giải quyết sẵn. Đọc giá trị này thay vì tự ánh xạ `service_id`. |
| `resolution` | string | Cách khắc phục sự cố. Chuỗi rỗng khi sự cố vẫn đang mở. |
| `opened_at` | string | Định dạng ISO 8601 kèm hậu tố `Z` |
| `resolved_at` | string hoặc null | Định dạng ISO 8601 kèm hậu tố `Z`, `null` khi đang mở |

`service_id` là một khóa ngoại dạng số, không phải slug hiển thị trên trang trạng thái. Khớp sự cố với dịch vụ bằng `service_name`.

Payload của sự cố là danh sách cột cố định và không chứa mốc thời gian sửa đổi. Sắp xếp hoặc tính thời gian tồn tại của sự cố theo `opened_at` và `resolved_at`. Trong ba tập hợp công khai, chỉ các mục changelog trả về `updated_at`. Các mục roadmap cũng trả về `created_at`, còn sự cố không trả về trường nào trong hai trường này.

Tab `resolved` trả về 30 sự cố được giải quyết gần đây nhất và dừng lại ở đó. Tab `open` trả về toàn bộ sự cố.

## Ghi chú

- Mọi endpoint đều công khai và không cần API key. Các endpoint roadmap bị giới hạn 30 request mỗi phút cho mỗi IP nguồn; các endpoint khác hiện không có rate limit riêng, vì vậy không nên poll trạng thái thường xuyên hơn mức bộ nhớ đệm 15 giây cho phép.
- Phản hồi là JSON qua HTTPS. Roadmap và sự cố không nhận tham số phân trang. Giới hạn duy nhất là `?tab=resolved` đối với sự cố, trả về tối đa 30 hàng.
- Đối với các phiên bản văn bản thuần hoặc HTML thô của changelog, hãy sử dụng feed [`/rss`](https://updates.foura.ai/rss) thay vì `/api/changelog`.

## Liên quan

- [Trạng thái dịch vụ](https://foura.ai/docs/updates-portal/status): Đọc cùng dữ liệu trên trình duyệt
- [Changelog](https://foura.ai/docs/updates-portal/changelog): Duyệt các mục với bộ lọc và phân trang
- [Roadmap](https://foura.ai/docs/updates-portal/roadmap): Bình chọn các mục trên UI
- [Sự cố đã biết](https://foura.ai/docs/updates-portal/issues): Xem các sự cố đang mở và đã giải quyết
- [Cổng thông tin cập nhật](https://foura.ai/docs/updates-portal/overview): Tổng quan về phần này
