# API do Updates Portal

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

O Portal de Atualizações disponibiliza uma pequena API JSON pública para você consultar status, obter entradas do changelog, acompanhar o roadmap e verificar problemas conhecidos a partir dos seus próprios sistemas. Nenhuma autenticação é necessária. A API disponibiliza apenas o texto em inglês; qualquer prefixo de idioma no path é ignorado.

## Base URL

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

## Status do serviço

`GET /api/v1/status`

Retorna o status operacional em tempo real de cada serviço FourA, além de incidentes ativos e recentes. Armazenado em cache no servidor por 15 segundos, portanto, fazer polling com frequência maior que essa retornará o mesmo 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 }
  ]
}
```

| Campo de nível superior | Tipo | Descrição |
|-----------------|------|-------------|
| `overall` | string | `operational` se todos os serviços estiverem operacionais, caso contrário, um dos valores de status de serviço |
| `updated_at` | string | Quando os dados de status foram gerados, ISO 8601 com sufixo `Z` |
| `services` | array | Uma entrada por serviço monitorado com `slug`, `name`, `description`, `status` atual e histórico de `daily` (até 90 dias) |
| `active_incidents` | array | Incidentes atualmente abertos |
| `recent_incidents` | array | Incidentes resolvidos nos últimos 14 dias, cada um com `id`, `service_slug`, `service_name`, `impact`, `title`, `status`, `started_at`, `resolved_at` e `duration_seconds` |

Valores de `status` do serviço: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`. Uma entrada de `daily` também pode indicar `no_data`, para um dia sem dados registrados. `internal_degraded_minutes` contabiliza o tempo sem impacto para o cliente.

Valores de `impact` do incidente: `minor` (desempenho degradado), `major` (interrupção parcial), `critical` (interrupção do serviço).

### Padrão de polling

Use este endpoint para integrar o status do FourA ao seu próprio painel ou sistema de alertas.

Quando os dados de status não puderem ser obtidos, o endpoint responde com `502` e `{"error": "Monitor unreachable"}`. Considere isso como um status desconhecido em vez de uma falha, e tente novamente na próxima consulta.

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

O `GET /api/status` legada retorna `410 Gone` e direciona os chamadores para cá.

## Registro de alterações

`GET /api/changelog`

Retorna entradas publicadas do changelog em ordem cronológica inversa.

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

Parâmetros de query:

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Número da página indexado em 1 |
| `limit` | integer | 20 | Entradas por página (máx. 50) |
| `category` | string | - | Filtrar por `new`, `improved` ou `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
}
```

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `id` | integer | ID da entrada |
| `title` | string | Título da entrada |
| `body` | string | Corpo em Markdown |
| `category` | string | `new`, `improved` ou `fixed` |
| `tags` | string | Um array JSON **codificado como string**. Faça o parse antes de usar: `json.loads(entry["tags"])`. |
| `published` | integer | Sempre `1` aqui. O endpoint retorna apenas entradas publicadas. |
| `published_at` | string | ISO 8601 com um sufixo `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, sem marcador de fuso |
| `updated_at` | string | Mesmo formato que `created_at` |

Os dois formatos de timestamp são diferentes de propósito: `published_at` é a data editorial e inclui um fuso, enquanto `created_at` e `updated_at` são timestamps de armazenamento. Ambos são UTC. Um parser que assumir o mesmo formato para todos os três falhará nos outros dois.

### RSS

O changelog completo (as 30 entradas mais recentes) também é publicado como RSS em:

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

Assine no Feedly, Miniflux, Thunderbird ou em qualquer leitor. O corpo do feed corresponde ao corpo do changelog, incluindo markdown renderizado para HTML.

## Roadmap

`GET /api/roadmap`

Retorna todos os itens publicados do roadmap, ordenados pela contagem de votos e depois pela data de criação.

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

Valores de `status` do item: `planned`, `in_progress`, `done`, `cancelled`. O quadro em [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) renderiza três colunas, portanto um item definido como `cancelled` chega até você por meio deste endpoint e nunca aparece na página.

`category` é um slug em letras minúsculas, não o rótulo exibido na página. Slugs em uso hoje: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Trate a lista como aberta, pois um novo item pode introduzir um novo slug.

`target_date` é texto livre (`"Q3 2026"`), não uma data. `completed_at` é `null` até que o item seja lançado, passando então para ISO 8601 com sufixo `Z` (`2026-09-01T10:15:30.000Z`), o mesmo formato de `published_at` em uma entrada de changelog. `created_at` usa `YYYY-MM-DD HH:MM:SS` em UTC. Os dois formatos diferem dentro do mesmo objeto, portanto faça o parse de cada campo individualmente.

### Votação

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

Alterna o voto em um único item do roadmap. Os votos são anônimos e vinculados ao IP do cliente mais os primeiros 50 caracteres do seu User-Agent. Chamar novamente remove o voto. Um item desconhecido ou não publicado responde com `404 {"error": "Not found"}`.

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

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

`voted` informa o estado pós-chamada: `true` se o seu voto foi adicionado, `false` se foi removido.

Os endpoints de roadmap, `GET /api/roadmap` e este, são limitados a 30 requests por minuto por IP de origem. Acima disso, a resposta é HTTP `429` com `{"error": "Too many votes, slow down"}`. Toda response de roadmap contém `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset` (um timestamp Unix em segundos), permitindo que você reduza a taxa antes de atingir o limite.

## Problemas Conhecidos

`GET /api/issues`

Retorna problemas rastreados pelo suporte do FourA.

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

Parâmetros de consulta:

| Parâmetro | Tipo | Padrão | Descrição |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` para problemas ativos, `resolved` para resolvidos/fechados |

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

| Campo | Tipo | Descrição |
|-------|------|-------------|
| `id` | integer | ID do problema |
| `title` | string | Resumo curto |
| `body` | string | Descrição em Markdown |
| `severity` | string | `low`, `medium`, `high` ou `critical` |
| `status` | string | `open`, `investigating`, `resolved` ou `closed` |
| `service_id` | integer or null | ID numérico do serviço afetado. `null` quando o problema não estiver vinculado a nenhum. |
| `service_name` | string or null | O nome de exibição do serviço, resolvido para você. Leia isto em vez de mapear `service_id` por conta própria. |
| `resolution` | string | Como foi corrigido. String vazia enquanto o problema estiver aberto. |
| `opened_at` | string | ISO 8601 com sufixo `Z` |
| `resolved_at` | string or null | ISO 8601 com sufixo `Z`, `null` enquanto estiver aberto |

`service_id` é uma chave estrangeira numérica, não o slug que você vê na página de status. Associe problemas a serviços usando `service_name`.

O payload do problema é uma lista fixa de colunas e não contém timestamp de modificação. Ordene ou calcule a idade de um problema por `opened_at` e `resolved_at`. Das três coleções públicas, apenas as entradas do changelog retornam `updated_at`. Os itens do roadmap também retornam `created_at`, e os problemas não retornam nenhum dos dois.

A aba `resolved` retorna os 30 problemas resolvidos mais recentemente e para por aí. A aba `open` retorna todos eles.

## Observações

- Todos os endpoints são públicos e não exigem chave de API. Os endpoints do roadmap são limitados a 30 requests por minuto por IP de origem; os outros não possuem rate limit próprio atualmente, portanto consulte o status com frequência não superior ao que o cache de 15 segundos justifica.
- As respostas são em JSON sobre HTTPS. Roadmap e problemas não aceitam parâmetros de paginação. O único limite é `?tab=resolved` em problemas, que retorna 30 linhas.
- Para versões em texto simples ou HTML puro do changelog, use o feed [`/rss`](https://updates.foura.ai/rss) em vez de `/api/changelog`.

## Relacionados

- [Status do Serviço](https://foura.ai/docs/updates-portal/status): Leia os mesmos dados no navegador
- [Changelog](https://foura.ai/docs/updates-portal/changelog): Navegue pelas entradas com filtros e paginação
- [Roadmap](https://foura.ai/docs/updates-portal/roadmap): Vote em itens na UI
- [Problemas Conhecidos](https://foura.ai/docs/updates-portal/issues): Leia problemas abertos e resolvidos
- [Portal de Atualizações](https://foura.ai/docs/updates-portal/overview): Visão geral da seção
