API Reference

Referencia completa de la API REST de rud1-es: endpoints M2M del agente rud1-fw, autenticación y API local del dispositivo.

Autenticación

rud1-es usa dos métodos de autenticación según el tipo de cliente:

1. Device API (M2M) — Para el agente rud1-fw

Las llamadas M2M usan autenticación Bearer Token en la cabecera HTTP:

Authorization: Bearer {TOKEN}

Existen dos tokens M2M distintos:

• DEVICE_API_SECRET — clave de organización configurada en rud1-es. Usada para registrar dispositivos e ingestar logs.
• device-token — token único por dispositivo, devuelto en la respuesta de registro. Usado por el agente para heartbeats, actualizaciones de firmware, etc.

2. Session Auth — Para el panel web

El dashboard de rud1-es usa autenticación basada en cookies (NextAuth). Se gestiona automáticamente por el navegador al iniciar sesión.

Endpoints del agente (M2M)

POST /api/v1/devices/register

Registra un nuevo dispositivo en rud1-es. El agente llama a este endpoint la primera vez que arranca y detecta que no tiene un token de dispositivo guardado.

Auth: Bearer {DEVICE_API_SECRET}

Request body

{
  "registrationCode": "RUD1-ABCD-1234",
  "serialNumber": "machine-id-from-etc",
  "hostname": "raspberry-pi-1",
  "firmwareVersion": "1.0.0",
  "platform": "linux",
  "arch": "arm64"
}

Response 200 OK

{
  "deviceId": "cuid...",
  "token": "device-bearer-token",
  "name": "Mi dispositivo"
}

POST /api/v1/devices/heartbeat

Envía métricas del sistema y estado del dispositivo. Se llama periódicamente según el intervalo configurado en cloud.heartbeat_interval (por defecto 60s).

Auth: Bearer {device-token}

Request body

{
  "cpuUsage": 23.5,
  "memoryUsage": 41.2,
  "temperature": 48.3,
  "diskUsage": 42.1,
  "uptime": 86400,
  "vpnConnected": true,
  "ipAddress": "192.168.1.100",
  "firmwareVersion": "1.0.0",
  "usbDevices": [
    {
      "vendorId": "0781",
      "productId": "5583",
      "vendorName": "SanDisk",
      "productName": "Ultra USB 3.0"
    }
  ],
  "networkInterfaces": [
    {
      "name": "eth0",
      "ipv4": "192.168.1.100",
      "up": true
    }
  ]
}

Response: 204 No Content

POST /api/v1/devices/logs

Ingesta logs del dispositivo en lote. Hasta 500 entradas por llamada. El agente agrupa los logs y los envía periódicamente junto con el heartbeat.

Auth: Bearer {DEVICE_API_SECRET}

Request body

{
  "deviceId": "cuid...",
  "logs": [
    {
      "level": "INFO",
      "source": "agent",
      "message": "Heartbeat sent successfully",
      "recordedAt": "2026-04-20T10:00:00Z"
    },
    {
      "level": "WARNING",
      "source": "vpn",
      "message": "WireGuard handshake timeout, retrying...",
      "recordedAt": "2026-04-20T10:00:05Z"
    }
  ]
}

Niveles de log válidos: DEBUG, INFO, WARNING, ERROR, CRITICAL

Response: 201 Created

GET /api/v1/devices/firmware/pending

Comprueba si hay una actualización de firmware pendiente para este dispositivo. El agente llama a este endpoint cada 10 minutos.

Auth: Bearer {device-token}

Response 200 — Actualización disponible

{
  "version": "1.2.0",
  "url": "https://rud1.es/api/v1/firmware/[id]/download",
  "sha256": "abc123def456..."
}

Response: 204 No Content cuando no hay actualización disponible.

POST /api/v1/devices/firmware/ack

Informa del resultado de una actualización de firmware (éxito o error).

Auth: Bearer {device-token}

{
  "deviceId": "cuid...",
  "version": "1.2.0",
  "success": true,
  "error": null
}

Response: 204 No Content

Endpoint de alertas (cron)

POST /api/v1/cron/alerts/sweep

Barre los dispositivos offline y abre alertas de tipo DEVICE_OFFLINE para aquellos que llevan más tiempo del umbral configurado sin enviar heartbeat.

Auth: Bearer {CRON_SECRET} o Bearer {DEVICE_API_SECRET}

Configura este endpoint en tu sistema de cron (cron-job.org, GitHub Actions scheduled, etc.):

curl -X POST https://rud1.es/api/v1/cron/alerts/sweep \
  -H "Authorization: Bearer {CRON_SECRET}"

# Intervalo recomendado: cada 5 minutos

API local del dispositivo (rud1-fw)

El agente rud1-fw expone una API HTTP local en el puerto 7070 (configurable). Esta API es usada por rud1-app para mostrar el panel local y puede ser usada también por sistemas externos en la misma red.