# API за Updates Portal

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

Updates Portal предоставя малко публично JSON API, за да можете да проверявате статус, да извличате записи от changelog, да следите roadmap и да проверявате известни проблеми от собствените си системи. Не се изисква удостоверяване. Това API предоставя само текст на английски език; езиковият префикс в пътя се игнорира.

## Базов URL

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

## Статус на услугата

`GET /api/v1/status`

Връща текущия работен статус на всяка FourA услуга, плюс активни и скорошни инциденти. Кешира се от страната на сървъра за 15 секунди, така че по-честото му извикване връща същия 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 }
  ]
}
```

| Поле от първо ниво | Тип | Описание |
|-----------------|------|-------------|
| `overall` | string | `operational`, ако всяка услуга е изправна, в противен случай една от стойностите за статус на услуга |
| `updated_at` | string | Кога са генерирани данните за статуса, ISO 8601 със суфикс `Z` |
| `services` | array | По един запис за всяка наблюдавана услуга с `slug`, `name`, `description`, текущ `status` и `daily` история (до 90 дни) |
| `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` (прекъсване на услугата).

### Модел на polling

Използвайте този endpoint за интегриране на статуса на FourA във вашето табло за управление или пейджинг система.

Когато данните за статуса не могат да бъдат извлечени, този endpoint връща `502` с `{"error": "Monitor unreachable"}`. Третирайте това като неизвестен статус вместо като грешен и опитайте отново при следващия poll.

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

Query параметри:

| Параметър | Тип | По подразбиране | Описание |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Номер на страницата (1-indexed) |
| `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 масив, **кодиран като string**. Парснете го преди употреба: `json.loads(entry["tags"])`. |
| `published` | integer | Тук винаги е `1`. Този endpoint връща само публикувани записи. |
| `published_at` | string | ISO 8601 със суфикс `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, без маркер за часова зона |
| `updated_at` | string | Същият формат като `created_at` |

Двата формата за timestamp са умишлено различни: `published_at` е редакционната дата и съдържа часова зона, докато `created_at` и `updated_at` са timestamps за съхранение. И двата са в UTC. Парсер, който очаква един и същ формат и за трите, ще даде грешка при другите два.

### RSS

Пълният changelog (30-те най-нови записа) се публикува и като RSS на:

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

Абонирайте се във Feedly, Miniflux, Thunderbird или друг четец. Съдържанието на фийда съвпада с това на changelog, включително markdown, рендериран като 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) показва три колони, така че елемент със статус `cancelled` достига до вас през този endpoint и никога не се появява на страницата.

`category` е slug с малки букви, а не етикетът, който страницата показва. Използвани slugs в момента: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Считайте списъка за отворен, тъй като нов елемент може да въведе нов slug.

`target_date` е свободен текст (`"Q3 2026"`), а не дата. `completed_at` е `null`, докато даден елемент не бъде издаден, след което е ISO 8601 с наставка `Z` (`2026-09-01T10:15:30.000Z`), същият формат като `published_at` на запис в changelog. `created_at` използва `YYYY-MM-DD HH:MM:SS` в UTC. Двата формата се различават в рамките на един обект, затова парсвайте всяко поле поотделно.

### Гласуване

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

Превключва глас за отделен roadmap елемент. Гласовете са анонимни и са обвързани с IP адреса на извикващия плюс първите 50 знака от неговия User-Agent. Повторно извикване премахва гласа. Непознат или непубликуван елемент връща отговор `404 {"error": "Not found"}`.

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

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

`voted` отчита състоянието след извикването: `true` ако гласът ви е бил добавен, `false` ако е бил премахнат.

Roadmap endpoint-ите, `GET /api/roadmap` и този, са ограничени до 30 заявки в минута за IP адрес на източника. При надвишаване отговорът е HTTP `429` с `{"error": "Too many votes, slow down"}`. Всеки roadmap response съдържа `X-RateLimit-Limit`, `X-RateLimit-Remaining` и `X-RateLimit-Reset` (Unix времево клеймо в секунди), така че можете да намалите темпото, преди да достигнете лимита.

## Известни проблеми

`GET /api/issues`

Връща проблеми, проследявани от поддръжката на FourA.

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

Query параметри:

| Параметър | Тип | По подразбиране | Описание |
|-----------|------|---------|-------------|
| `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 | Как е разрешен проблемът. Празен низ, докато проблемът е отворен. |
| `opened_at` | string | ISO 8601 със суфикс `Z` |
| `resolved_at` | string or null | ISO 8601 със суфикс `Z`, `null` докато е отворен |

`service_id` е числов foreign key, а не slug стойността, която виждате на страницата за статус. Съпоставяйте проблемите с услугите по `service_name`.

Обектът с данни за проблема е с фиксиран списък от колони и не съдържа времево клеймо за модификация. Сортирайте или следете възрастта на даден проблем по `opened_at` и `resolved_at`. От трите публични колекции само записите в changelog връщат `updated_at`. Елементите в roadmap връщат също и `created_at`, а проблемите не връщат нито едно от двете.

Разделът `resolved` връща 30-те най-скоро разрешени проблема и спира дотам. Разделът `open` връща всички тях.

## Бележки

- Всички endpoint-и са публични и не изискват API key. Endpoint-ите за roadmap са ограничени до 30 заявки в минута за IP адрес на източника; останалите в момента нямат собствен rate limit, така че правете polling на статуса не по-често, отколкото позволява 15-секундният му кеш.
- Отговорите са JSON през HTTPS. За roadmap и issues не се приемат параметри за пагинация. Единственото ограничение е `?tab=resolved` при issues, което връща 30 реда.
- За версии на changelog в свободен текст или чист HTML използвайте емисията [`/rss`](https://updates.foura.ai/rss) вместо `/api/changelog`.

## Свързани

- [Статус на услугите](https://foura.ai/docs/updates-portal/status): Прегледайте същите данни в браузъра
- [Changelog](https://foura.ai/docs/updates-portal/changelog): Преглеждайте записи с филтри и пагинация
- [Roadmap](https://foura.ai/docs/updates-portal/roadmap): Гласувайте за елементи в UI-а
- [Известни проблеми](https://foura.ai/docs/updates-portal/issues): Прегледайте отворени и разрешени проблеми
- [Портал за актуализации](https://foura.ai/docs/updates-portal/overview): Преглед на раздела
