# Updates Portal API

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

업데이트 포털은 사용자의 자체 시스템에서 상태를 폴링하고 변경 로그 항목을 수집하며 로드맵을 확인하고 알려진 문제를 점검할 수 있도록 소규모 퍼블릭 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 | 모니터링 대상 서비스당 항목 1개(`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`(서비스 중단).

### 폴링 패턴

이 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"
```

쿼리 매개변수:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `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 또는 원하는 리더기에서 구독하세요. 피드 본문은 HTML로 렌더링된 마크다운을 포함하여 변경 로그 본문과 일치합니다.

## 로드맵

`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`은(는) 페이지에 출력되는 레이블이 아닌 소문자 slug입니다. 현재 사용 중인 slug: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. 새 항목에 새 slug가 도입될 수 있으므로 이 목록은 계속 추가될 수 있습니다.

`target_date`은(는) 날짜가 아닌 자유 텍스트(`"Q3 2026"`)입니다. `completed_at`은(는) 항목이 배포되기 전까지 `null`이며, 배포 후에는 변경 로그 항목의 `published_at`과 동일한 형식인 `Z` 접미사가 붙은 ISO 8601(`2026-09-01T10:15:30.000Z`)이 됩니다. `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로 제한됩니다. 이를 초과하면 `{"error": "Too many votes, slow down"}`가 포함된 HTTP `429`가 반환됩니다. 모든 로드맵 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"
```

Query parameters:

| 매개변수 | 유형 | 기본값 | 설명 |
|-----------|------|---------|-------------|
| `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 또는 null | 영향을 받는 서비스의 숫자 ID. 특정 서비스에 연결되지 않은 이슈인 경우 `null`. |
| `service_name` | string 또는 null | 자동 확인된 서비스 표시 이름. `service_id`을 직접 매핑하는 대신 이 값을 읽으십시오. |
| `resolution` | string | 해결 방법. 이슈가 열려 있는 동안에는 빈 문자열입니다. |
| `opened_at` | string | `Z` 접미사가 붙은 ISO 8601 |
| `resolved_at` | string 또는 null | `Z` 접미사가 붙은 ISO 8601, 열려 있는 동안에는 `null` |

`service_id`은 상태 페이지에 표시되는 슬러그가 아니라 숫자 외래 키입니다. 이슈와 서비스를 `service_name` 기준으로 매칭하십시오.

이슈 payload는 고정된 컬럼 목록이며 수정 타임스탬프를 포함하지 않습니다. 이슈 정렬이나 경과 시간 계산에는 `opened_at` 및 `resolved_at`을 사용하십시오. 세 가지 공개 컬렉션 중 changelog 항목만 `updated_at`을 반환합니다. 로드맵 항목은 `created_at`도 반환하며, 이슈는 둘 다 반환하지 않습니다.

`resolved` 탭은 가장 최근에 해결된 이슈 30개만 반환합니다. `open` 탭은 전체 이슈를 반환합니다.

## 참고 사항

- 모든 endpoint는 공개되어 있으며 API 키가 필요하지 않습니다. 로드맵 endpoint는 소스 IP당 분당 30개의 request로 제한됩니다. 다른 endpoint는 현재 자체적인 rate limit이 없으므로 15초 캐시 주기에 맞춰 상태를 폴링하십시오.
- 응답은 HTTPS 기반 JSON입니다. 로드맵과 이슈는 페이징 파라미터를 지원하지 않습니다. 유일한 제한은 이슈의 `?tab=resolved`으로, 30개 행을 반환합니다.
- changelog의 일반 텍스트 또는 원시 HTML 버전이 필요한 경우 `/api/changelog` 대신 [`/rss`](https://updates.foura.ai/rss) 피드를 사용하십시오.

## 관련 항목

- [서비스 상태](https://foura.ai/docs/updates-portal/status): 브라우저에서 동일한 데이터 확인
- [Changelog](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): 섹션 개요
