Documentación

Referencia de endpoints

Catálogo completo del API. Todas las rutas están bajo el prefijo https://www.rud1.es/api/v1/public.

Resumen

Método	Ruta	Scope	Descripción
GET	/devices	devices:read	Listar dispositivos
GET	/devices/{id}	devices:read	Detalle de un dispositivo
GET	/devices/{id}/metrics	metrics:read	Series temporales de métricas
GET	/devices/{id}/events	logs:read	Eventos del dispositivo
GET	/alerts	alerts:read	Listar alertas
POST	/alerts/{id}/acknowledge	alerts:write	Reconocer una alerta
POST	/alerts/{id}/resolve	alerts:write	Resolver una alerta

💡 Todas las respuestas incluyen los headers X-RateLimit-*. Las listas son cursor-paginadas: usa el campo nextCursor de la respuesta como valor de ?cursor=… para la siguiente página.

Dispositivos

GET /devices

Lista los dispositivos de la organización de la clave API.

Parámetro	Tipo	Descripción
limit	1..100 (default 25)	Tamaño de página
cursor	cuid	Cursor opaco para paginar
status	DeviceStatus	ONLINE / OFFLINE / CONNECTING / ERROR / PROVISIONING / REBOOTING / UPDATING

ejemplo

GET /api/v1/public/devices?status=ONLINE&limit=10
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": [
    {
      "id": "clxxxxxxxxxxxxxxxxxxxxxxx",
      "name": "PLC línea 3",
      "serialNumber": "RUD1-000123",
      "status": "ONLINE",
      "model": "Rud1 Mini",
      "firmwareVersion": "1.4.2",
      "lastSeen": "2026-05-05T22:11:38.512Z",
      "ipAddress": "192.168.1.42",
      "location": "Planta 2 - Norte",
      "createdAt": "2026-04-12T10:00:00.000Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

GET /devices/{id}

Devuelve el detalle de un dispositivo. Si el ID no pertenece a tu organización responde 404 not_found (no revelamos la existencia de recursos de otras organizaciones).

ejemplo

GET /api/v1/public/devices/clxxxxxxxxxxxxxxxxxxxxxxx
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": {
    "id": "clxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "PLC línea 3",
    "serialNumber": "RUD1-000123",
    "status": "ONLINE",
    "model": "Rud1 Mini",
    "firmwareVersion": "1.4.2",
    "lastSeen": "2026-05-05T22:11:38.512Z",
    "ipAddress": "192.168.1.42",
    "location": "Planta 2 - Norte",
    "notes": null,
    "agentDeviceName": "rud1-planta2",
    "agentDeviceLocation": "Planta 2 - Norte",
    "agentTimezone": "Europe/Madrid",
    "createdAt": "2026-04-12T10:00:00.000Z"
  }
}

GET /devices/{id}/metrics

Series temporales de métricas de sistema (CPU, memoria, disco, temperatura, carga). El agente captura una muestra cada ~5 minutos.

Parámetro	Tipo	Descripción
from	ISO 8601	Inicio del rango (default: hace 1 hora)
to	ISO 8601	Fin del rango (default: ahora)
limit	1..1000 (default 200)	Máximo de muestras

ejemplo

GET /api/v1/public/devices/clxx.../metrics?from=2026-05-05T20:00:00Z
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": [
    {
      "capturedAt": "2026-05-05T22:10:00.000Z",
      "cpuPct": 18.4,
      "memPct": 41.2,
      "diskUsedPct": 32.8,
      "tempCpu": 48.1,
      "loadAvg1": 0.42
    }
  ],
  "window": {
    "from": "2026-05-05T20:00:00.000Z",
    "to": "2026-05-05T22:11:38.512Z"
  }
}

GET /devices/{id}/events

Stream de eventos del dispositivo: heartbeats, alertas que se abren y se resuelven, ciclo de vida del agente, USB, etc.

Parámetro	Tipo	Descripción
limit	1..200 (default 50)	Tamaño de página
cursor	cuid	Cursor de paginación
severity	string	Filtrar por INFO, WARNING, ERROR o CRITICAL
type	string	Filtrar por tipo (ej. 'alert.high_cpu')

ejemplo

GET /api/v1/public/devices/clxx.../events?severity=ERROR&limit=10
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": [
    {
      "id": "clyyyyyyyyyyyyyyyyyyyyyyy",
      "type": "alert.vpn_down",
      "severity": "ERROR",
      "message": "Secure tunnel 'wg0' is disconnected",
      "data": {
        "interfaceName": "wg0",
        "endpoint": "203.0.113.1:51820",
        "peerCount": 2
      },
      "createdAt": "2026-05-05T22:09:14.000Z"
    }
  ],
  "pagination": { "nextCursor": "clzzz...", "hasMore": true }
}

Alertas

GET /alerts

Lista las alertas de tu organización. Por defecto solo devuelve las que están en estado ACTIVE.

Parámetro	Tipo	Descripción
state	ACTIVE \| ACKNOWLEDGED \| RESOLVED	Estado a filtrar (default ACTIVE)
severity	string	INFO / WARNING / ERROR / CRITICAL
deviceId	cuid	Filtrar por un dispositivo concreto
limit	1..100 (default 25)	Tamaño de página
cursor	cuid	Cursor de paginación

ejemplo

GET /api/v1/public/alerts?state=ACTIVE&severity=CRITICAL
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": [
    {
      "id": "claaaaaaaaaaaaaaaaaaaaaaa",
      "state": "ACTIVE",
      "severity": "CRITICAL",
      "message": "CPU usage 96.4% exceeds 90%",
      "payload": { "cpuUsage": 96.4, "threshold": 90 },
      "deviceId": "clxxxxxxxxxxxxxxxxxxxxxxx",
      "ruleId": "clrrrrrrrrrrrrrrrrrrrrrrrrr",
      "acknowledgedAt": null,
      "resolvedAt": null,
      "createdAt": "2026-05-05T22:08:01.123Z"
    }
  ],
  "pagination": { "nextCursor": null, "hasMore": false }
}

POST /alerts/{id}/acknowledge

Marca una alerta como reconocida. Idempotente: si ya está reconocida, devuelve la fila sin cambios. Si la alerta ya está RESOLVED responde 409 alert_already_resolved.

ejemplo

POST /api/v1/public/alerts/claaa.../acknowledge
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": {
    "id": "claaaaaaaaaaaaaaaaaaaaaaa",
    "state": "ACKNOWLEDGED",
    "severity": "CRITICAL",
    "message": "CPU usage 96.4% exceeds 90%",
    "acknowledgedAt": "2026-05-05T22:12:00.000Z",
    "resolvedAt": null,
    "createdAt": "2026-05-05T22:08:01.123Z"
  }
}

POST /alerts/{id}/resolve

Marca la alerta como resuelta. Idempotente: si ya estaba resuelta no cambia el resolvedAt original — el timestamp se preserva como evidencia del primer cierre.

ejemplo

POST /api/v1/public/alerts/claaa.../resolve
Authorization: Bearer rud1_sk_...

200 OK
{
  "data": {
    "id": "claaaaaaaaaaaaaaaaaaaaaaa",
    "state": "RESOLVED",
    "severity": "CRITICAL",
    "message": "CPU usage 96.4% exceeds 90%",
    "acknowledgedAt": "2026-05-05T22:12:00.000Z",
    "resolvedAt": "2026-05-05T22:14:33.000Z",
    "createdAt": "2026-05-05T22:08:01.123Z"
  }
}

ℹ️ Reconocer ≠ resolver. ACKNOWLEDGED indica que alguien ha visto la alerta y está actuando sobre ella; RESOLVED indica que la condición se ha corregido. Una alerta puede pasar directamente de ACTIVE a RESOLVED sin pasar por ACKNOWLEDGED.

← Autenticación Errores →