API Portal cập nhật

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.

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 }
  ]
}
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.

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.

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
{
  "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.

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

Các giá trị của status cho mục: planned, in_progress, done, cancelled. Bảng tại 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"}.

curl -X POST https://updates.foura.ai/api/roadmap/12/vote
{ "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.

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
{
  "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 thay vì /api/changelog.
Cập nhật: 5 tháng 11, 2026