API REST

La web de Atalaya usa una API REST con JSON, y esa misma API está disponible para scripts y otras herramientas. Todas las rutas empiezan por /api/v1/.

Autenticación

La API usa la misma sesión que la web, guardada en la cookie atalaya_session. Desde un script:

curl -k -c cookies.txt -H 'Content-Type: application/json' \
     -d '{"username":"admin","password":"..."}' https://atalaya.lan/api/v1/session
curl -k -b cookies.txt https://atalaya.lan/api/v1/hosts

Las peticiones que cambian algo deben enviar el cuerpo como application/json. Si incluyen la cabecera Origin, debe coincidir con la dirección del servidor. Para los asistentes de IA hay un servidor MCP con sus propios tokens, y Prometheus puede leer /metrics con uno de ellos (ver Integraciones).

Rutas

Método y ruta	Qué hace	Permiso
`GET /api/v1/health`	Estado del servicio y de la conexión a MariaDB.	Ninguno
`POST /api/v1/session`	Inicia sesión con `username` y `password`.	Ninguno
`GET /api/v1/session`	Usuario de la sesión actual.	Sesión
`DELETE /api/v1/session`	Cierra la sesión.	Sesión
`POST /api/v1/session/mfa`	Segundo paso: con `mfa_token` (lo devuelve `POST /session` con `{"mfa_required": true}` si el usuario tiene 2FA) y `code`, crea la sesión.	Ninguno
`GET /api/v1/session/totp`	Estado de la verificación en dos pasos del usuario (`enabled`, `required`, `recovery_left`).	Sesión
`POST /api/v1/session/totp/setup`	Con `password`, genera el secreto (`secret`, `uri` otpauth).	Sesión
`POST /api/v1/session/totp/enable`	Con `code`, la activa y devuelve `recovery_codes` (una sola vez).	Sesión
`POST /api/v1/session/totp/disable`, `.../recovery`	Con `password` y `code`: desactivarla, o generar códigos de recuperación nuevos.	Sesión
`DELETE /api/v1/users/{id}/totp`	Quita la verificación en dos pasos de un usuario y cierra sus sesiones.	Administrador
`GET /api/v1/status`	Versión, esquema, modo del ping y recuento de equipos por estado.	Sesión
`GET /api/v1/hosts`	Lista de equipos con el resultado de su último ping.	Sesión
`POST /api/v1/hosts`	Da de alta un equipo.	Administrador
`GET /api/v1/hosts/{id}`	Un equipo.	Sesión
`PUT /api/v1/hosts/{id}`	Cambia los campos enviados de un equipo.	Administrador
`DELETE /api/v1/hosts/{id}`	Borra un equipo.	Administrador
`GET /api/v1/hosts/{id}/checks`	Comprobaciones de un equipo con su estado.	Sesión
`POST /api/v1/hosts/{id}/checks`	Añade una comprobación.	Administrador
`GET /api/v1/checks/{id}`	Una comprobación.	Sesión
`PUT /api/v1/checks/{id}`	Cambia los campos enviados de una comprobación.	Administrador
`DELETE /api/v1/checks/{id}`	Borra una comprobación (la de presencia no).	Administrador
`POST /api/v1/checks/{id}/run`	La ejecuta ahora.	Sesión
`GET /api/v1/checks/{id}/results`	Sus últimos 200 resultados.	Sesión
`GET /api/v1/satellites`	Satélites (agentes en modo satélite): estado, subredes, equipos, relevo y cola.	Sesión
`PUT /api/v1/satellites/{agente}`	Activa o desactiva el satélite de un agente: `enabled`, `relay` y `subnets` (lista de redes).	Administrador
`GET /api/v1/alerts`	Alertas activas.	Sesión
`GET /api/v1/alerts/history`	Últimas 200 alertas, también resueltas.	Sesión
`POST /api/v1/alerts/{id}/ack`	Marca una alerta como vista (`comment` opcional).	Administrador
`GET /api/v1/channels`	Canales de aviso, sin secretos.	Administrador
`POST /api/v1/channels`	Añade un canal.	Administrador
`PUT /api/v1/channels/{id}`	Cambia un canal.	Administrador
`DELETE /api/v1/channels/{id}`	Borra un canal.	Administrador
`POST /api/v1/channels/{id}/test`	Envía un mensaje de prueba.	Administrador
`GET /api/v1/hosts/{id}/addresses`	Direcciones adicionales del equipo, con el estado de su ping.	Sesión
`POST /api/v1/hosts/{id}/addresses`	Añade una dirección: `address`, `label` opcional y `ping` (`true` por defecto).	Administrador
`DELETE /api/v1/hosts/{id}/addresses/{n}`	Quita una dirección y su ping.	Administrador
`GET /api/v1/inventory?q=...`	Equipos con su inventario; `q` es la búsqueda de Inventario.	Sesión
`GET /api/v1/inventory/export?q=...&sep=;`	Lo mismo en CSV (`sep` `,` por defecto, o `;`).	Sesión
`GET /api/v1/inventory/changes`	Últimos 300 cambios de inventario de todos los equipos.	Sesión
`GET /api/v1/hosts/{id}/inventory`	Ficha completa: hardware, discos, sistema, actualizaciones, ficha administrativa y cambios.	Sesión
`GET /api/v1/hosts/{id}/packages?q=`	Paquetes instalados, con filtro por nombre.	Sesión
`PUT /api/v1/hosts/{id}/asset`	Ficha administrativa: `asset_tag`, `location`, `owner`, `supplier`, `model`, `serial`, `purchase_date`, `purchase_price`, `warranty_until` y `notes`; `null` borra el dato.	Administrador
`POST /api/v1/hosts/{id}/inventory/snmp`	Lee el equipo por SNMP (`credential_id`, `port` opcional) y lo repetirá cada día.	Administrador
`GET /api/v1/pve/clusters`	Clústeres de Proxmox con su estado, sin el token.	Sesión
`POST /api/v1/pve/clusters`	Añade un clúster: `name`, `base_url`, `token_id`, `token_secret` (se guarda cifrado), `tls_mode` (`pin`, `ca` o `none`), `interval_s`, `backup_max_age_h`, `auto_create`.	Administrador
`GET /api/v1/pve/clusters/{id}`	Detalle con nodos, invitados y almacenamientos.	Sesión
`PATCH /api/v1/pve/clusters/{id}`	Cambia campos; `token_secret` solo si se manda; `forget_pins: true` olvida las huellas TLS.	Administrador
`POST /api/v1/pve/clusters/{id}/poll`	Lee el clúster ya.	Administrador
`DELETE /api/v1/pve/clusters/{id}`	Quita el clúster (los equipos creados se conservan).	Administrador
`PATCH /api/v1/pve/guests/{id}`	`expect_running` (`true`, `false` o `null` para seguir `onboot`), `backup_expected`, `host_id` (enlazar con un equipo; `null` para no enlazar) o `relink: true`.	Administrador
`GET /api/v1/silences`	Silencios y ventanas de mantenimiento (los terminados hace más de una semana no salen).	Sesión
`POST /api/v1/silences`	Crea un silencio: `host_id` o `tag` (sin ellos, todos los equipos), `check_name` opcional, `reason`, y `duration_min`, `ends_at` (ISO 8601 UTC) o `schedule` (mantenimiento recurrente).	Administrador
`PATCH /api/v1/silences/{id}`	`enabled` (`false` lo termina) o `ends_at`.	Administrador
`DELETE /api/v1/silences/{id}`	Borra un silencio.	Administrador
`GET /api/v1/credentials`	Credenciales SSH y SNMP, sin secretos (de las claves SSH, la pública).	Administrador
`POST /api/v1/credentials`	Crea una: `kind` `ssh` (genera la clave) o `snmp` (`version` `2c` con `community`, o `3` con `user`, `level`, `auth_proto`, `auth_pass`, `priv_proto`, `priv_pass`).	Administrador
`PUT /api/v1/credentials/{id}`	Cambia el nombre o los datos SNMP (un secreto enviado como `********` se conserva).	Administrador
`DELETE /api/v1/credentials/{id}`	La borra si ninguna comprobación la usa.	Administrador
`GET /api/v1/mibs`	MIB SNMP subidas, con su estado (objetos, sin resolver, módulos que faltan).	Administrador
`POST /api/v1/mibs`	Sube una MIB: `{"filename", "content"}` (texto, hasta 400 KB). Si ya había otra del mismo módulo, la sustituye.	Administrador
`DELETE /api/v1/mibs/{id}`	La borra (las comprobaciones que usan sus OID siguen funcionando).	Administrador
`GET /api/v1/mibs/objects?q=`	Busca objetos legibles por nombre u OID: `name`, `oid`, `kind`, `syntax`, `units`, `descr`, `enums`.	Administrador
`GET /api/v1/tokens`	Tokens de acceso de los agentes de IA.	Administrador
`POST /api/v1/tokens`	Crea un token (`name`, `scope` `read`, `operate` o `config`, `tags`, `rate_limit`); el valor solo se devuelve en esta respuesta.	Administrador
`PATCH /api/v1/tokens/{id}`	Activa o desactiva (`enabled`).	Administrador
`DELETE /api/v1/tokens/{id}`	Borra un token.	Administrador
`GET /api/v1/config/export`	Equipos, comprobaciones y reglas en YAML.	Administrador
`POST /api/v1/config/import`	Aplica un YAML (cuerpo del mensaje); crea o actualiza por nombre y no borra nada. Devuelve lo hecho y los errores.	Administrador
`POST /api/v1/config/import/check`	Igual, pero solo dice qué haría.	Administrador
`GET /api/v1/agents`	Agentes Linux con su último informe.	Sesión
`POST /api/v1/agents/tokens`	Código de alta de un solo uso (60 min); `host_id` opcional. Devuelve también la huella de la web (`pin`).	Administrador
`POST /api/v1/agents/{id}/update`	Pide al agente que se actualice a la versión del servidor (lo hace en su siguiente informe).	Administrador
`POST /api/v1/digest/send`	Manda ya el resumen semanal por los canales de correo activos.	Administrador
`POST /api/v1/agents/update-all`	Lo mismo para todos los agentes desactualizados.	Administrador
`DELETE /api/v1/agents/{id}`	Revoca un agente: su certificado deja de valer.	Administrador
`GET /api/v1/hosts/{id}/metrics`	Series de métricas del equipo con su último valor, y datos de su agente.	Sesión
`GET /api/v1/metrics/{serie}/{segundos}`	Puntos `[ms, media, mín, máx]` de una serie en ese periodo (de 60 s a 2 años).	Sesión
`GET /api/v1/rules`	Reglas de alerta de las métricas y lista de métricas posibles.	Sesión
`POST /api/v1/rules`	Crea una regla: `name`, `metric`, `op` (`>` o `<`), `threshold`, `for_minutes`, `severity`, `host_id` (null para todos), `enabled`.	Administrador
`PUT /api/v1/rules/{id}`	Cambia una regla (solo los campos que se envíen).	Administrador
`DELETE /api/v1/rules/{id}`	Borra una regla; las de serie solo se desactivan.	Administrador

Equipos

Campos que se pueden enviar al crear o modificar un equipo:

Campo	Tipo	Notas
`name`	texto	Obligatorio al crear; único; hasta 128 caracteres.
`address`	texto	Obligatorio al crear; IP o nombre DNS.
`availability_mode`	texto	`24x7` (por defecto), `intermittent` o `scheduled`.
`satellite`	número, null o «auto»	Quién lo vigila: el número de un satélite (el `id` del agente), `null` para el servidor o `"auto"` para que lo decida su subred.
`notes`	texto o null	Hasta 4000 caracteres.
`schedule`	lista o null	Franjas del modo horario: `[{"days":[1,2,3,4,5],"from":"08:00","to":"20:00"}]`, días del 1 (lunes) al 7.
`grace_s`	número	Periodo de gracia en segundos tras encenderse (300 por defecto).
`parent_id`	número o null	Equipo del que depende (ver dependencias).
`tags`	lista	Hasta 10 etiquetas de letras, números, `-` y `_`.
`enabled`	booleano	`false` deja de vigilarlo.
`ping`	booleano	Solo al crear: `false` para no crear la comprobación de presencia.

Ejemplo:

curl -k -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"name":"nas","address":"192.168.1.10"}' https://atalaya.lan/api/v1/hosts

La respuesta incluye además el estado (status, power_state), el último ping (rtt_ms, loss_pct, resolved_address, ping_message, ping_checked_at), el número de comprobaciones (checks_total, checks_failing), las alertas activas (alerts_firing) y las fechas de alta y modificación. Todas las fechas van en UTC con formato ISO 8601.

Comprobaciones

Campo	Tipo	Notas
`type`	texto	`icmp`, `tcp`, `http`, `dns`, `script`, `ssh`, `snmp`, `tls` (certificado) o `domain` (dominio).
`name`	texto	Opcional; único en el equipo.
`params`	objeto	Propios de cada tipo (ver abajo). Comunes a todos: `address` (otra dirección del equipo; por defecto, la principal) y `max_severity` (`warning` para que como mucho avise).
`interval_s`	número	Segundos entre comprobaciones (60).
`timeout_ms`	número	Tiempo máximo de respuesta (5000).
`fail_threshold`	número	Fallos seguidos para dar la alarma (2).
`enabled`	booleano

Parámetros: icmp admite count, warn_rtt_ms, crit_rtt_ms, warn_loss y crit_loss; tcp, port (obligatorio); http, url, expect_status, contains, method (GET o HEAD), verify_tls, follow_redirects, cert_warn_days y cert_crit_days; dns, query (obligatorio), record_type, expect y server. tcp, http y dns admiten además warn_ms y crit_ms. script: command (ruta absoluta de un plugin) y args (lista de textos). ssh: credential_id, user, command (obligatorios), port, mode (nagios o exit0), contains, warn, crit y host_key (huella SHA256:…, se aprende sola). snmp: credential_id (obligatorio), port e interfaces (lista de nombres).

curl -k -b cookies.txt -H 'Content-Type: application/json' \
     -d '{"type":"http","params":{"url":"https://{address}:8006/","verify_tls":false}}' \
     https://atalaya.lan/api/v1/hosts/3/checks

Canales

type es ntfy, telegram, matrix o email, y config lleva sus datos: server, topic y token (ntfy); bot_token y chat_id (Telegram); homeserver, room_id y access_token (Matrix); smtp_url, username, password, from y to (correo). Además, min_severity (warning o critical), send_recovery y enabled. Los secretos se devuelven como ********; al editar, si se envían así, se conserva el valor guardado.

Errores

Los errores devuelven el código HTTP correspondiente y un cuerpo como este:

{"error": {"code": "duplicate_name", "message": "Ya hay un equipo con ese nombre."}}