# API de Updates Portal

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

El Portal de Actualizaciones expone una pequeña API pública en JSON para que puedas consultar el estado, incorporar entradas del changelog, seguir el roadmap y revisar problemas conocidos desde tus propios sistemas. No requiere autenticación. La API solo ofrece el texto en inglés; cualquier prefijo de idioma en la ruta se ignora.

## URL base

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

## Estado del servicio

`GET /api/v1/status`

Devuelve el estado operativo en vivo de cada servicio de FourA, además de los incidentes activos y recientes. Se almacena en caché del lado del servidor durante 15 segundos, por lo que consultar con mayor frecuencia devolverá el mismo 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 nivel superior | Tipo | Descripción |
|-----------------|------|-------------|
| `overall` | string | `operational` si todos los servicios funcionan correctamente; de lo contrario, uno de los valores de estado del servicio |
| `updated_at` | string | Momento en que se generaron los datos de estado, ISO 8601 con sufijo `Z` |
| `services` | array | Una entrada por servicio monitoreado con `slug`, `name`, `description`, `status` actual e historial de `daily` (hasta 90 días) |
| `active_incidents` | array | Incidentes abiertos actualmente |
| `recent_incidents` | array | Incidentes resueltos de los últimos 14 días, cada uno con `id`, `service_slug`, `service_name`, `impact`, `title`, `status`, `started_at`, `resolved_at` y `duration_seconds` |

Valores de `status` del servicio: `operational`, `degraded`, `partial_outage`, `major_outage`, `maintenance`. Una entrada de `daily` también puede indicar `no_data`, para un día sin datos registrados. `internal_degraded_minutes` contabiliza el tiempo sin impacto en el cliente.

Valores de `impact` de incidentes: `minor` (rendimiento degradado), `major` (interrupción parcial), `critical` (interrupción del servicio).

### Patrón de sondeo

Usa este endpoint para integrar el estado de FourA en tu propio panel o sistema de alertas.

Cuando no se puedan obtener los datos de estado, el endpoint responderá `502` con `{"error": "Monitor unreachable"}`. Trata esto como un estado desconocido en lugar de erróneo e inténtalo de nuevo en el siguiente sondeo.

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

El `GET /api/status` heredado devuelve `410 Gone` y redirige a los emisores de llamadas aquí.

## Registro de cambios

`GET /api/changelog`

Devuelve las entradas publicadas del registro de cambios en orden cronológico inverso.

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

Parámetros de consulta:

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|---------|-------------|
| `page` | integer | 1 | Número de página con índice base 1 |
| `limit` | integer | 20 | Entradas por página (máx. 50) |
| `category` | string | - | Filtrar por `new`, `improved` o `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 | Descripción |
|-------|------|-------------|
| `id` | integer | ID de la entrada |
| `title` | string | Título de la entrada |
| `body` | string | Cuerpo en Markdown |
| `category` | string | `new`, `improved` o `fixed` |
| `tags` | string | Un array JSON **codificado como string**. Analízalo antes de usarlo: `json.loads(entry["tags"])`. |
| `published` | integer | Siempre `1` aquí. El endpoint solo devuelve entradas publicadas. |
| `published_at` | string | ISO 8601 con sufijo `Z` |
| `created_at` | string | `YYYY-MM-DD HH:MM:SS`, UTC, sin indicador de zona |
| `updated_at` | string | Mismo formato que `created_at` |

Los dos formatos de timestamp son diferentes a propósito: `published_at` es la fecha editorial e incluye una zona, mientras que `created_at` y `updated_at` son timestamps de almacenamiento. Ambos son UTC. Un parser que asuma un solo formato para los tres lanzará un error con los otros dos.

### RSS

El changelog completo (las 30 entradas más recientes) también se publica como RSS en:

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

Suscríbete en Feedly, Miniflux, Thunderbird o cualquier lector. El cuerpo del feed coincide con el del changelog, incluido el markdown renderizado a HTML.

## Roadmap

`GET /api/roadmap`

Devuelve cada elemento publicado del roadmap, ordenado por cantidad de votos y luego por fecha de creación.

```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` del elemento: `planned`, `in_progress`, `done`, `cancelled`. El tablero en [updates.foura.ai/roadmap](https://updates.foura.ai/roadmap) renderiza tres columnas, por lo que un elemento establecido en `cancelled` te llega a través de este endpoint y nunca aparece en la página.

`category` es un slug en minúsculas, no la etiqueta que imprime la página. Slugs en uso hoy: `api`, `infrastructure`, `developer-experience`, `dashboard`, `billing`, `analytics`, `authentication`. Trata la lista como abierta, ya que un nuevo elemento puede introducir uno nuevo.

`target_date` es texto libre (`"Q3 2026"`), no una fecha. `completed_at` es `null` hasta que se publica un elemento, luego ISO 8601 con un sufijo `Z` (`2026-09-01T10:15:30.000Z`), el mismo formato que el `published_at` de una entrada del changelog. `created_at` usa `YYYY-MM-DD HH:MM:SS` en UTC. Los dos formatos difieren dentro de un mismo objeto, así que analiza cada campo por separado.

### Votación

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

Alterna un voto en un único elemento del roadmap. Los votos son anónimos y están vinculados a la IP de quien llama más los primeros 50 caracteres de su User-Agent. Llamar de nuevo elimina el voto. Un elemento desconocido o no publicado responde `404 {"error": "Not found"}`.

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

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

`voted` informa el estado posterior a la llamada: `true` si tu voto fue agregado, `false` si fue eliminado.

Los endpoints de roadmap, `GET /api/roadmap` y este mismo, están limitados a 30 requests por minuto por IP de origen. Si se supera ese límite, la respuesta es HTTP `429` con `{"error": "Too many votes, slow down"}`. Cada response de roadmap incluye `X-RateLimit-Limit`, `X-RateLimit-Remaining` y `X-RateLimit-Reset` (una marca de tiempo Unix en segundos), para que puedas reducir la velocidad antes de alcanzar el límite.

## Problemas conocidos

`GET /api/issues`

Devuelve los problemas registrados por el soporte de FourA.

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

Parámetros de consulta:

| Parámetro | Tipo | Predeterminado | Descripción |
|-----------|------|---------|-------------|
| `tab` | string | `open` | `open` para incidencias activas, `resolved` para resueltas o cerradas |

```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 | Descripción |
|-------|------|-------------|
| `id` | integer | ID del problema |
| `title` | string | Resumen breve |
| `body` | string | Descripción en Markdown |
| `severity` | string | `low`, `medium`, `high` o `critical` |
| `status` | string | `open`, `investigating`, `resolved` o `closed` |
| `service_id` | integer or null | ID numérico del servicio afectado. `null` cuando el problema no está vinculado a ninguno. |
| `service_name` | string or null | Nombre para mostrar del servicio, ya resuelto. Lee esto en lugar de mapear `service_id` tú mismo. |
| `resolution` | string | Cómo se solucionó. Cadena vacía mientras el problema esté abierto. |
| `opened_at` | string | ISO 8601 con sufijo `Z` |
| `resolved_at` | string or null | ISO 8601 con sufijo `Z`, `null` mientras esté abierto |

`service_id` es una clave externa numérica, no el slug que ves en la página de estado. Asocia problemas con servicios mediante `service_name`.

El payload del problema es una lista fija de columnas y no incluye marca de tiempo de modificación. Ordena o calcula la antigüedad de un problema mediante `opened_at` y `resolved_at`. De las tres colecciones públicas, solo las entradas del changelog devuelven `updated_at`. Los elementos del roadmap también devuelven `created_at`, y los problemas no devuelven ninguno de los dos.

La pestaña `resolved` devuelve los 30 problemas resueltos más recientes y termina ahí. La pestaña `open` los devuelve todos.

## Notas

- Todos los endpoints son públicos y no requieren API key. Los endpoints del roadmap están limitados a 30 solicitudes por minuto por IP de origen; los demás no tienen rate limit propio actualmente, así que consulta el estado con una frecuencia no mayor a la que justifica su caché de 15 segundos.
- Las respuestas son JSON sobre HTTPS. El roadmap y los problemas no aceptan parámetros de paginación. El único límite es `?tab=resolved` en problemas, que devuelve 30 filas.
- Para versiones en texto plano o HTML sin procesar del changelog, usa el feed [`/rss`](https://updates.foura.ai/rss) en lugar de `/api/changelog`.

## Relacionado

- [Service Status](https://foura.ai/docs/updates-portal/status): Consulta los mismos datos en el navegador
- [Changelog](https://foura.ai/docs/updates-portal/changelog): Explora entradas con filtros y paginación
- [Roadmap](https://foura.ai/docs/updates-portal/roadmap): Vota por elementos en la UI
- [Known Issues](https://foura.ai/docs/updates-portal/issues): Consulta problemas abiertos y resueltos
- [Updates Portal](https://foura.ai/docs/updates-portal/overview): Descripción general de la sección
