# Updates Portal API

> URL: https://foura.ai/ja/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秒間キャッシュされるため、それ以上の頻度でポーリングしても同じペイロードが返されます。

```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`、最大 90 日間の `daily` 履歴を含む） |
| `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` (サービス停止)。

### ポーリングパターン

このエンドポイントを使用して、FourA のステータスを独自のダッシュボードやページングシステムに連携します。

ステータスデータを取得できない場合、エンドポイントは `{"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 | 1ページあたりのエントリ数 (最大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`。このエンドポイントは公開済みエントリのみを返します。 |
| `published_at` | string | `Z` 接尾辞付きの ISO 8601 |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`、UTC、タイムゾーンマーカーなし |
| `updated_at` | string | `created_at` と同じ形式 |

これら2つのタイムスタンプ形式は意図的に異なります。`published_at` は公開日でありタイムゾーンを含みますが、`created_at` と `updated_at` はストレージのタイムスタンプです。どちらもUTCです。3つすべてが同一形式であると想定するパーサーは、他の2つで例外を発生させます。

### RSS

完全な変更履歴（最新30件のエントリ）は、次の場所でRSSとしても公開されています:

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

Feedly、Miniflux、Thunderbird、または任意のリーダーで購読できます。フィードの本文は、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) のボードには3つの列が表示されるため、`cancelled` に設定されたアイテムはこの endpoint 経由で取得され、ページ上には表示されません。

`category` は小文字のスラッグであり、ページに表示されるラベルではありません。現在使用中のスラッグ: `api`、`infrastructure`、`developer-experience`、`dashboard`、`billing`、`analytics`、`authentication`。新しいアイテムによって新しいスラッグが追加される可能性があるため、このリストは固定ではないものとして扱ってください。

`target_date` は日付ではなく、自由形式のテキスト（`"Q3 2026"`）です。`completed_at` はアイテムがリリースされるまで `null` であり、リリース後は `Z` サフィックス付きの ISO 8601（`2026-09-01T10:15:30.000Z`）になります。これは更新履歴エントリの `published_at` と同じ形式です。`created_at` は UTC の `YYYY-MM-DD HH:MM:SS` を使用します。1つのオブジェクト内で2つの形式が異なるため、各フィールドは個別にパースしてください。

### 投票

`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 に制限されています。これを超えると、`{"error": "Too many votes, slow down"}` を含む HTTP `429` が返されます。すべてのロードマップ response には `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset`（秒単位の Unix タイムスタンプ）が含まれるため、制限に達する前に request 頻度を落とすことができます。

## 既知の問題

`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 | 解決方法。障害が未解決（open）の間は空文字列。 |
| `opened_at` | string | 末尾に `Z` が付いた ISO 8601 形式 |
| `resolved_at` | string or null | 末尾に `Z` が付いた ISO 8601 形式。未解決の間は `null`。 |

`service_id` は数値の外部キーであり、ステータスページに表示されるスラッグではありません。障害とサービスの照合には `service_name` を使用してください。

障害のペイロードは固定カラムリストであり、更新日時のタイムスタンプは含まれません。障害の並び替えや経過時間の判定には `opened_at` および `resolved_at` を使用してください。3つの公開コレクションのうち、更新履歴（changelog）エントリのみが `updated_at` を返します。ロードマップ項目は `created_at` も返しますが、障害はいずれも返しません。

`resolved` タブは直近で解決された上位30件の障害を返し、それ以降は返しません。`open` タブはすべての障害を返します。

## 備考

- すべての endpoint は公開されており、API キーは不要です。ロードマップの endpoint は送信元 IP あたり毎分30 request に制限されています。その他の endpoint には現在独自の rate limit はありませんが、ステータスのキャッシュ期間が15秒であるため、それ以上の頻度でポーリングを行わないでください。
- response は HTTPS 経由の JSON です。ロードマップおよび障害ではページネーション用パラメータを受け付けません。唯一の上限は障害の `?tab=resolved` であり、30件を返します。
- プレーンテキストまたは未加工の HTML 形式の更新履歴を取得する場合は、`/api/changelog` ではなく [`/rss`](https://updates.foura.ai/rss) フィードを使用してください。

## 関連リソース

- [サービスステータス](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): セクションの概要
