Monitores vía API

nota

La gestión de monitores vía API está disponible en los planes Pro y Enterprise.

Endpoints

Método	Ruta	Scope	Descripción
GET	/api/v1/monitors	monitors:read	Listar monitores
GET	/api/v1/monitors/{id}	monitors:read	Detalle de un monitor
POST	/api/v1/monitors	monitors:write	Crear monitor
PATCH	/api/v1/monitors/{id}	monitors:write	Actualizar monitor (parcial)
DELETE	/api/v1/monitors/{id}	monitors:write	Eliminar monitor

---

GET /api/v1/monitors

Parámetros de consulta:

Parámetro	Tipo	Descripción
page	int	Página (default: 1)
per_page	int	Resultados por página (default: 25, máx: 100)
status	string	Filtrar por up, down, degraded o unknown
type	string	Filtrar por tipo: http, tcp, dns, ssl, heartbeat, ping
q	string	Búsqueda por nombre o target

Ejemplo:

curl -H "Authorization: Bearer <token>" \
  "https://back.statusinspector.com/api/v1/monitors?type=http&status=down"

---

Campos del objeto Monitor

Los campos presentes dependen del monitor_type.

Campos comunes (todos los tipos)

Campo	Tipo	Descripción
id	string	ID del monitor
name	string	Nombre
monitor_type	string	http, tcp, dns, ssl, heartbeat, ping
target	string	URL, IP o hostname objetivo
method	string	Método HTTP (GET, POST, etc.) — solo HTTP
interval_sec	int	Segundos entre checks
timeout_ms	int	Timeout en ms
group_id	int|null	ID de grupo (null si sin grupo)
is_paused	bool	Si está pausado
is_in_maintenance	bool	Si está en mantenimiento
last_status	string	Estado agregado actual: up, down, degraded, unknown
last_checked_at	string|null	ISO 8601 UTC del último check
next_run_at	string|null	ISO 8601 UTC del próximo check programado
created_at	string	ISO 8601 UTC
updated_at	string	ISO 8601 UTC
synthetic_trace_body_detail	string	none, truncated o full

Campos adicionales — tipo http

Campo	Tipo	Descripción
editor_ui_profile	string|null	http_endpoint, api_full, api o null
port	int|null	Puerto opcional
expected_http_codes	string|null	Códigos esperados, p.ej. "200,201"
keyword	string|null	Texto buscado en la respuesta
api_expected_content_type	string|null	Content-Type esperado
api_expected_body_contains	string|null	Substring esperado en el body
api_max_latency_ms	int|null	Umbral de latencia para estado DEGRADED
synthetic_enabled	bool	Si el modo sintético multi-step está activo
api_json_assertions_json	object|null	Reglas de assertions JSON (ver sección)
api_headers_json	object|null	Headers HTTP personalizados
api_body	string|null	Body de la petición
synthetic_steps_json	object|null	Escenario multi-step declarativo
api_auth_type	string	none, bearer, basic o api_key
api_auth_basic_user	string|null	Usuario (autenticación Basic)
api_auth_api_key_header	string|null	Nombre del header de API key
ssl_expiry_warn_days	int|null	Días de antelación para aviso SSL (null = predeterminado)
ssl_expiry_last_not_after	string|null	Fecha de expiración del certificado (snapshot)

Los secretos (api_auth_bearer_token, api_auth_basic_pass, api_auth_api_key_value) nunca se devuelven en respuestas GET. Solo se aceptan en escritura.

Campos adicionales — tipo heartbeat

Campo	Tipo	Descripción
heartbeat_token	string|null	Token secreto para el endpoint de ping
heartbeat_period_sec	int|null	Ventana esperada entre pings válidos (segundos)
heartbeat_grace_sec	int|null	Tolerancia adicional antes de marcar DOWN
heartbeat_notify_on_late	bool	Si alertar al entrar en DEGRADED por retraso
heartbeat_payload_policy	string	none o status_ok
heartbeat_payload_status_key	string|null	Clave JSON a evaluar con política status_ok
heartbeat_last_ping_at	string|null	ISO 8601 UTC del último ping aceptado

Campos adicionales — tipo ssl

Campo	Tipo	Descripción
ssl_expiry_warn_days	int|null	Días de antelación para aviso SSL
ssl_expiry_last_not_after	string|null	Snapshot de expiración del certificado

---

POST /api/v1/monitors — Crear monitor

Acepta payload plano o formato JSON:API:

{
  "name": "API de producción",
  "monitor_type": "http",
  "target": "https://api.ejemplo.com/health",
  "method": "GET",
  "interval_sec": 60,
  "timeout_ms": 5000,
  "expected_http_codes": "200",
  "api_json_assertions_json": [
    { "path": "status", "op": "equals", "value": "ok" }
  ]
}

Campos requeridos

Campo	Descripción
name	Nombre del monitor
monitor_type	Tipo: http, tcp, dns, ssl, heartbeat, ping
target	URL o host objetivo (no requerido en heartbeat)
interval_sec	Intervalo entre checks
timeout_ms	Timeout en ms

Campos opcionales HTTP

Todos los campos de la sección de detalle HTTP son aceptados. Para autenticación:

{
  "api_auth_type": "bearer",
  "api_auth_bearer_token": "mi-token-secreto"
}

Assertions JSON

Formato de cada regla en api_json_assertions_json:

[
  { "path": "data.status",  "op": "equals",          "value": "ok" },
  { "path": "data.count",   "op": "greater_than",     "value": "0" },
  { "path": "error",        "op": "is_null" },
  { "path": "items",        "op": "contains",         "value": "producto" }
]

Operadores disponibles: equals, not_equals, contains, not_contains, greater_than, less_than, is_null, is_not_null, regex.

Respuesta exitosa: 201 Created con el monitor creado.

---

PATCH /api/v1/monitors/{id} — Actualizar monitor

Solo los campos enviados se actualizan (actualización parcial). Mismo formato que POST.

curl -X PATCH \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"is_paused": true}' \
  "https://back.statusinspector.com/api/v1/monitors/42"

---

DELETE /api/v1/monitors/{id} — Eliminar monitor

curl -X DELETE \
  -H "Authorization: Bearer <token>" \
  "https://back.statusinspector.com/api/v1/monitors/42"

Respuesta:

{
  "data": { "id": "42", "type": "monitor", "attributes": { "deleted": true } },
  "meta": { ... }
}