# API Portalu Aktualizacji

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

Portal Updates udostępnia małe publiczne JSON API, dzięki któremu możesz odpytywać o status, pobierać wpisy changelogu, śledzić roadmapę i sprawdzać znane problemy bezpośrednio z własnych systemów. Uwierzytelnianie nie jest wymagane. API zwraca wyłącznie tekst w języku angielskim; prefiks języka w ścieżce jest ignorowany.

## Bazowy URL

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

## Status usługi

`GET /api/v1/status`

Zwraca aktualny stan operacyjny każdej usługi FourA oraz aktywne i niedawne incydenty. Odpowiedź jest buforowana po stronie serwera przez 15 sekund, więc częstsze wysyłanie zapytań zwraca ten sam 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 }
  ]
}
```

| Pole najwyższego poziomu | Typ | Opis |
|-----------------|------|-------------|
| `overall` | string | `operational`, jeśli każda usługa działa poprawnie, w przeciwnym razie jedna z wartości statusu usługi |
| `updated_at` | string | Kiedy dane o statusie zostały wygenerowane, ISO 8601 z sufiksem `Z` |
| `services` | array | Jeden wpis na monitorowaną usługę z `slug`, `name`, `description`, bieżącym `status` i historią `daily` (do 90 dni) |
| `active_incidents` | array | Aktualnie otwarte incydenty |
| `recent_incidents` | array | Rozwiązane incydenty z ostatnich 14 dni, każdy z `id`, `service_slug`, `service_name`, `impact`, `title`, `status`, `started_at`, `resolved_at` i `duration_seconds` |

Wartości `status` usługi: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`. Wpis `daily` może również mieć wartość `no_data` w przypadku dnia bez zarejestrowanych danych. `internal_degraded_minutes` zlicza czas bez wpływu na klientów.

Wartości `impact` incydentu: `minor` (obniżona wydajność), `major` (częściowa awaria), `critical` (awaria usługi).

### Wzorzec odpytywania (polling)

Użyj tego endpointu, aby zintegrować status FourA z własnym panelem lub systemem powiadomień.

Gdy danych o statusie nie można pobrać, endpoint zwraca `502` z `{"error": "Monitor unreachable"}`. Należy traktować to jako status nieznany, a nie błąd, i ponowić próbę przy następnym odpytaniu.

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

Starszy `GET /api/status` zwraca `410 Gone` i przekierowuje wywołujących tutaj.

## Dziennik zmian

`GET /api/changelog`

Zwraca opublikowane wpisy dziennika zmian w odwrotnej kolejności chronologicznej.

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

Parametry zapytania:

| Parametr | Typ | Wartość domyślna | Opis |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Numer strony indeksowany od 1 |
| `limit` | integer | 20 | Liczba wpisów na stronę (maks. 50) |
| `category` | string | - | Filtruj do `new`, `improved` lub `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
}
```

| Pole | Typ | Opis |
|-------|------|-------------|
| `id` | integer | ID wpisu |
| `title` | string | Tytuł wpisu |
| `body` | string | Treść Markdown |
| `category` | string | `new`, `improved` lub `fixed` |
| `tags` | string | Tablica JSON **zakodowana jako string**. Sparsuj ją przed użyciem: `json.loads(entry["tags"])`. |
| `published` | integer | Tutaj zawsze `1`. Endpoint zwraca tylko opublikowane wpisy. |
| `published_at` | string | ISO 8601 z sufiksem `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, bez oznaczenia strefy |
| `updated_at` | string | Taki sam format jak `created_at` |

Dwa formaty znaczników czasu różnią się celowo: `published_at` to data redakcyjna zawierająca strefę, podczas gdy `created_at` i `updated_at` to znaczniki czasu zapisu. Oba są w formacie UTC. Parser, który zakłada jeden format dla wszystkich trzech, zgłosi błąd przy pozostałych dwóch.

### RSS

Pełny changelog (30 najnowszych wpisów) jest również publikowany jako RSS pod adresem:

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

Subskrybuj w Feedly, Miniflux, Thunderbird lub dowolnym czytniku. Treść kanału odpowiada treści changeloga, w tym markdown wyrenderowany do HTML.

## Roadmapa

`GET /api/roadmap`

Zwraca każdy opublikowany element roadmapy, posortowany według liczby głosów, a następnie czasu utworzenia.

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

Wartości `status` elementu: `planned`, `in_progress`, `done`, `cancelled`. Tablica pod adresem [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) wyświetla trzy kolumny, więc element z wartością `cancelled` trafi do Ciebie przez ten endpoint i nigdy nie pojawi się na stronie.

`category` to slug pisany małymi literami, a nie etykieta wyświetlana na stronie. Obecnie używane slugi: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Listę należy traktować jako otwartą, ponieważ nowy element może wprowadzić kolejny slug.

`target_date` to zwykły tekst (`"Q3 2026"`), a nie data. `completed_at` ma wartość `null` do momentu wdrożenia elementu, a następnie format ISO 8601 z sufiksem `Z` (`2026-09-01T10:15:30.000Z`), identycznie jak pole `published_at` we wpisie changeloga. `created_at` używa formatu `YYYY-MM-DD HH:MM:SS` w strefie UTC. Te dwa formaty różnią się w obrębie jednego obiektu, dlatego każde pole należy parsować oddzielnie.

### Głosowanie

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

Przełącza głos na pojedynczym elemencie roadmapy. Głosy są anonimowe i powiązane z adresem IP wywołującego oraz pierwszymi 50 znakami jego nagłówka User-Agent. Ponowne wywołanie usuwa głos. Nieznany lub nieopublikowany element zwraca `404 {"error": "Not found"}`.

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

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

`voted` zwraca stan po wykonaniu wywołania: `true`, jeśli Twój głos został dodany, `false`, jeśli został usunięty.

Endpointy roadmapy, `GET /api/roadmap` oraz ten, są ograniczone do 30 requestów na minutę na źródłowy adres IP. Po przekroczeniu tego limitu odpowiedź to HTTP `429` z `{"error": "Too many votes, slow down"}`. Każda response roadmapy zawiera nagłówki `X-RateLimit-Limit`, `X-RateLimit-Remaining` i `X-RateLimit-Reset` (znacznik czasu Unix w sekundach), dzięki czemu możesz zwolnić przed osiągnięciem limitu.

## Znane problemy

`GET /api/issues`

Zwraca zgłoszenia śledzone przez wsparcie FourA.

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

Parametry zapytania:

| Parametr | Typ | Domyślnie | Opis |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` dla aktywnych problemów, `resolved` dla rozwiązanych/zamkniętych |

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

| Pole | Typ | Opis |
|-------|------|-------------|
| `id` | integer | ID problemu |
| `title` | string | Krótkie podsumowanie |
| `body` | string | Opis w formacie Markdown |
| `severity` | string | `low`, `medium`, `high` lub `critical` |
| `status` | string | `open`, `investigating`, `resolved` lub `closed` |
| `service_id` | integer or null | Numeryczny identyfikator usługi, której dotyczy problem. `null`, gdy problem nie jest powiązany z żadną usługą. |
| `service_name` | string or null | Nazwa wyświetlana usługi, rozwiązana automatycznie. Użyj tej wartości zamiast samodzielnie mapować `service_id`. |
| `resolution` | string | Sposób rozwiązania. Pusty ciąg znaków, dopóki problem pozostaje otwarty. |
| `opened_at` | string | Format ISO 8601 z sufiksem `Z` |
| `resolved_at` | string or null | Format ISO 8601 z sufiksem `Z`, `null` dopóki problem jest otwarty |

`service_id` to numeryczny klucz obcy, a nie slug widoczny na stronie statusu. Dopasowuj problemy do usług za pomocą `service_name`.

Payload problemu zawiera stałą listę kolumn i nie posiada sygnatury czasowej modyfikacji. Sortuj lub określaj wiek problemu według `opened_at` i `resolved_at`. Spośród trzech publicznych kolekcji tylko wpisy dziennika zmian zwracają `updated_at`. Pozycje roadmapy zwracają dodatkowo `created_at`, a problemy nie zwracają żadnego z nich.

Karta `resolved` zwraca 30 ostatnio rozwiązanych problemów i na tym kończy. Karta `open` zwraca je wszystkie.

## Uwagi

- Wszystkie endpointy są publiczne i nie wymagają klucza API. Endpointy roadmapy są ograniczone do 30 żądań na minutę na źródłowy adres IP; pozostałe nie mają obecnie własnego limitu zapytań (rate limit), więc sprawdzaj status nie częściej, niż uzasadnia to 15-sekundowa pamięć podręczna.
- Odpowiedzi są zwracane w formacie JSON przez HTTPS. Roadmapa i problemy nie przyjmują parametrów stronicowania. Jedynym limitem jest `?tab=resolved` dla problemów, który zwraca 30 wierszy.
- W przypadku wersji dziennika zmian w postaci zwykłego tekstu lub czystego HTML użyj kanału [`/rss`](https://updates.foura.ai/rss) zamiast `/api/changelog`.

## Powiązane

- [Status usług](https://foura.ai/docs/updates-portal/status): Przeglądaj te same dane w przeglądarce
- [Dziennik zmian](https://foura.ai/docs/updates-portal/changelog): Przeglądaj wpisy z filtrami i paginacją
- [Roadmapa](https://foura.ai/docs/updates-portal/roadmap): Głosuj na elementy w interfejsie użytkownika
- [Znane problemy](https://foura.ai/docs/updates-portal/issues): Przeglądaj otwarte i rozwiązane problemy
- [Portal aktualizacji](https://foura.ai/docs/updates-portal/overview): Przegląd sekcji
