API
La API REST de SONAR para integraciones: dirección base, autenticación con clave de API, endpoints (dispositivos, comandos, clientes, alertas, checks, tareas, software, actualizaciones) y errores.
Qué es esto y cuándo usarlo
SONAR expone una API REST sobre HTTPS. La consola usa la misma API, así que lo que un rol puede hacer en la consola, un script puede hacerlo a través de la API con una clave de un usuario que tenga ese rol.
Úsela para llevar el inventario de dispositivos a una CMDB, abrir tickets a partir de alertas, ejecutar un comando o un script en dispositivos desde un programador externo, o lanzar búsquedas e instalaciones de actualizaciones dentro de una ventana de cambios.
Dirección base y autenticación
Todas las rutas de esta página son relativas a la dirección de la API de su instalación, que se entrega con ella. Esta página la escribe como https://api.example.com.
Autentique cada petición con una clave de API en la cabecera X-API-KEY. Cree la clave en Admin Center › Settings › API Keys; consulte Claves de API.
curl -s \
-H "X-API-KEY: <your-api-key>" \
-H "Content-Type: application/json" \
"https://api.example.com/agents/?page=1&page_size=10"La petición se ejecuta como el usuario de la clave: tiene los permisos del rol de ese usuario, y se le aplica el Client & Site Access del rol. Una llamada que el rol no permite responde 403. Consulte Permisos de los roles.
Convenciones
JSON de entrada y de salida. Envíe los cuerpos como JSON con
Content-Type: application/json.Identificador del dispositivo. Las rutas de dispositivo llevan el
agent_iddel dispositivo, un identificador largo que devuelveGET /agents/. No es el hostname.Otros identificadores. Los clientes, sitios, checks, tareas, scripts, alertas y actualizaciones se identifican por su
idnumérico.Barra final. Todas las rutas terminan en
/.Respuestas de acciones. Muchas acciones responden con un mensaje de texto plano, por ejemplo
Checks will now be run on WS-0001, en lugar de un objeto.Acciones en vivo. Hacer ping, ejecutar un comando, ejecutar un script y esperar su salida, reiniciar y apagar contactan con el dispositivo mientras la petición está abierta. Necesitan que el dispositivo esté en línea.
Muchos dispositivos a la vez. Para actuar sobre muchos dispositivos, use
POST /agents/actions/bulk/en lugar de una petición por dispositivo. Pone el trabajo en cola y responde de inmediato.
Paginación y filtros de la lista de dispositivos
GET /agents/ está paginado y responde con este sobre:
page
Número de página, empezando por 1
page_size
Dispositivos por página. Por defecto 10, máximo 100
search
Texto libre sobre hostname, descripción, sistema operativo, cliente, sitio, direcciones IP y usuario conectado
client
Un id de cliente
clients
Varios ids de cliente, separados por comas
site
Un id de sitio
type
server o workstation
plat
windows, linux o darwin
os
Texto contenido en el nombre del sistema operativo
availability
online, offline12h, offline24h, offline7d, overdue, maintenance o archived
ordering
Campo por el que ordenar, por ejemplo hostname; anteponga - para invertir el orden
Cada resultado incluye, entre otros, agent_id, hostname, client_name, site_name, status, plat, operating_system, last_seen, needs_reboot, has_patches_pending y maintenance_mode.
Endpoints
Dispositivos
GET
/agents/
Lista los dispositivos, paginados y filtrados como se indica arriba
List Agents
GET
/agents/<agent_id>/
Detalles completos de un dispositivo, incluidos hardware, discos, checks y campos personalizados
List Agents
PUT
/agents/<agent_id>/
Cambia un dispositivo. Acepta description, site, monitoring_type, maintenance_mode, time_zone, check_interval, offline_time, overdue_time, los tres indicadores overdue_*_alert y custom_fields
Edit Agent
DELETE
/agents/<agent_id>/
Quita el agente del dispositivo y el dispositivo de SONAR
Uninstall Agents
GET
/agents/<agent_id>/ping/
Pregunta al dispositivo si responde. Devuelve {"name": ..., "status": "online"} o "offline"
List Agents
POST
/agents/maintenance/bulk/
Activa o desactiva el modo de mantenimiento para todo un cliente o sitio: {"type": "Client", "id": 3, "action": true}
Edit Agent
GET
/agents/<agent_id>/history/
Comandos y scripts ejecutados en el dispositivo, con sus resultados
List Agent History
GET
/agents/<agent_id>/notes/
Notas de un dispositivo
List Notes
POST
/agents/notes/
Añade una nota: {"agent_id": "...", "note": "..."}
Manage Notes
Comandos, scripts y energía
POST
/agents/<agent_id>/cmd/
Ejecuta un comando y devuelve su salida. Cuerpo más abajo
Send Command
POST
/agents/<agent_id>/runscript/
Ejecuta un script de la biblioteca. Cuerpo más abajo
Run Scripts
POST
/agents/actions/bulk/
Ejecuta un comando, un script o una acción de actualizaciones en muchos dispositivos. Cuerpo más abajo
Run Bulk Operations
POST
/agents/<agent_id>/reboot/
Reinicia ahora
Reboot Agents
PATCH
/agents/<agent_id>/reboot/
Programa un reinicio en un dispositivo Windows: {"datetime": "2026-10-01T22:00"}
Reboot Agents
POST
/agents/<agent_id>/shutdown/
Apaga
Reboot Agents
POST
/agents/<agent_id>/wol/
Envía Wake-on-LAN
Send Wake-on-LAN
GET
/scripts/
Lista los scripts de la biblioteca, con su id
List Scripts
GET
/scripts/<id>/
Un script con su cuerpo
List Scripts
POST, PUT, DELETE
/scripts/, /scripts/<id>/
Crea, cambia o elimina un script
Manage Scripts
Ejecutar un comando:
shell es cmd o powershell en Windows, y /bin/bash en Linux y macOS. Para otro shell, envíe "shell": "custom" con su ruta en custom_shell. La petición espera la salida hasta timeout segundos.
Ejecutar un script:
output
Efecto
wait
Espera y devuelve la salida del script
forget
Responde de inmediato; el resultado aparece en History del dispositivo
email
Envía el resultado por correo electrónico. Añada "emailMode": "default", o "emailMode": "custom" con "emails": [...]
collector
Guarda la última línea de la salida, o toda ella con "save_all_output": true, en el campo personalizado indicado en "custom_field"
note
Guarda la salida como una nota en el dispositivo
Ejecutar en muchos dispositivos:
mode
command (con cmd, shell, timeout, run_as_user), script (con los campos del script), o patch (con patchMode: scan o install)
target
agents con "agents": ["<agent_id>", ...], client con "client": <id>, site con "site": <id>, o all
monType
all, servers o workstations
osType
all, windows, linux o darwin
La respuesta indica cuántos dispositivos recibieron el trabajo, por ejemplo ... will now be run on 120 agents. Check the History tab on the agent to view the results.
Clientes y sitios
GET
/clients/
Clientes con sus sitios y sus recuentos de dispositivos
List Clients
POST
/clients/
Crea un cliente con su primer sitio: {"client": {"name": "CLIENT-A"}, "site": {"name": "SITE-01"}}
Manage Clients
GET
/clients/<id>/
Un cliente
List Clients
PUT
/clients/<id>/
Cambia un cliente: {"client": {"name": "..."}}
Manage Clients
DELETE
/clients/<id>/?move_to_site=<site-id>
Elimina un cliente. Si tiene dispositivos, move_to_site indica adónde van
Manage Clients
GET
/clients/sites/
Todos los sitios
List Sites
POST
/clients/sites/
Crea un sitio: {"site": {"client": 3, "name": "SITE-02"}}
Manage Sites
GET, PUT
/clients/sites/<id>/
Lee o cambia un sitio: {"site": {"name": "..."}}
List Sites / Manage Sites
DELETE
/clients/sites/<id>/?move_to_site=<site-id>
Elimina un sitio y traslada sus dispositivos. Un cliente conserva al menos un sitio
Manage Sites
Ambos cuerpos de creación aceptan también custom_fields.
Alertas
PATCH
/alerts/
Consulta alertas. Cuerpo más abajo
List Alerts
GET
/alerts/<id>/
Una alerta
List Alerts
PUT
/alerts/<id>/
{"type": "resolve"}, {"type": "snooze", "snooze_days": 2} o {"type": "unsnooze"}
Manage Alerts
DELETE
/alerts/<id>/
Elimina una alerta
Manage Alerts
POST
/alerts/bulk/
{"bulk_action": "resolve", "alerts": [1, 2]}, o snooze con snooze_days
Manage Alerts
GET
/alerts/templates/
Plantillas de alerta
List Alert Templates
Cuerpo de la consulta:
timeFilter es un número de días. resolvedFilter: false y snoozedFilter: false devuelven solo las alertas abiertas y no pospuestas. Envíe siempre timeFilter para que la respuesta sea pequeña.
Checks
GET
/agents/<agent_id>/checks/
Checks de un dispositivo, incluidos los heredados de políticas, con su último resultado en check_result
List Checks
POST
/checks/
Añade un check. Envíe "agent": "<agent_id>" y los ajustes del check
Manage Checks
GET, PUT, DELETE
/checks/<id>/
Lee, cambia o elimina un check
List Checks / Manage Checks
POST
/checks/<agent_id>/run/
Ejecuta ahora todos los checks del dispositivo
Run Checks
POST
/checks/client/<id>/csbulkrun/
Ejecuta los checks en todos los dispositivos de un cliente. Use site para un sitio
Run Checks
POST
/checks/<result-id>/reset/
Restablece un check a correcto. <result-id> es el id dentro de check_result
Manage Checks
POST
/checks/<agent_id>/resetall/
Restablece todos los checks del dispositivo a correcto
Manage Checks
PATCH
/checks/<result-id>/history/
Historial de resultados. {"timeFilter": 7} lo limita a los últimos días
List Checks
Los ajustes de un check dependen de su tipo. La forma más rápida de conocerlos es crear un check en la consola y leerlo después con GET /checks/<id>/.
Tareas automatizadas
GET
/agents/<agent_id>/tasks/
Tareas de un dispositivo, incluidas las heredadas de políticas
List Tasks
POST
/tasks/
Crea una tarea. Envíe "agent": "<agent_id>" y los ajustes de la tarea
Manage Tasks
GET, PUT, DELETE
/tasks/<id>/
Lee, cambia o elimina una tarea
List Tasks / Manage Tasks
POST
/tasks/<id>/run/
Ejecuta una tarea ahora. Para una tarea de política, añada {"agent_id": "<agent_id>"}
Run Tasks
Igual que con los checks, cree una tarea en la consola y léala con GET /tasks/<id>/ para conocer los campos.
Software
GET
/software/<agent_id>/
Software instalado en un dispositivo
List Software
PUT
/software/<agent_id>/
Pide a un dispositivo Windows una lista de software actualizada
Manage Software
GET
/software/chocos/
Paquetes disponibles para instalar
List Software
POST
/software/<agent_id>/
Instala un paquete en un dispositivo Windows: {"name": "7zip"}. Siga el proceso en las acciones pendientes del dispositivo
Manage Software
Actualizaciones (Windows Update)
GET
/winupdate/<agent_id>/
Actualizaciones conocidas en un dispositivo. Filtros: state (pending, downloaded, installed, failed), severity (Critical, Important, Moderate, Low, other), q (título o KB). Añada page y page_size (hasta 100) para una respuesta paginada
Manage Windows Updates
POST
/winupdate/<agent_id>/scan/
Busca actualizaciones en el dispositivo
Manage Windows Updates
POST
/winupdate/<agent_id>/install/
Instala las actualizaciones aprobadas
Manage Windows Updates
PUT
/winupdate/<id>/
Fija la acción de una actualización: {"action": "approve"}, o ignore, inherit, nothing
Manage Windows Updates
Para buscar o instalar actualizaciones en muchos dispositivos, use POST /agents/actions/bulk/ con "mode": "patch".
Registro de auditoría y acciones pendientes
PATCH
/logs/audit/
Consulta el registro de auditoría. Cuerpo más abajo
View Audit Logs
GET
/agents/<agent_id>/pendingactions/
Acciones en cola de un dispositivo, como reinicios programados e instalaciones de software
List Pending Actions
DELETE
/logs/pendingactions/<id>/
Cancela una acción pendiente
Manage Pending Actions
Cuerpo de la consulta de auditoría:
Otros filtros: agentFilter (una lista de agent_id), clientFilter (ids de cliente) y objectFilter (por ejemplo user, role, agent). La respuesta es {"audit_logs": [...], "total": <n>}. Mantenga rowsPerPage entre 25 y 1000.
Errores
400
Un mensaje de texto, por ejemplo "Unable to contact the agent", o errores de campo como {"name": ["This field may not be blank."]}
El dispositivo está sin conexión para una acción en vivo, o el cuerpo no superó la validación
401
{"detail": "Invalid token."}, {"detail": "The token has expired."}, {"detail": "User inactive or deleted."} o {"detail": "Authentication credentials were not provided."}
La clave es incorrecta, ha caducado, pertenece a un usuario desactivado o no se envió
403
{"detail": "You do not have permission to perform this action."}
Al usuario de la clave le falta el permiso, o el dispositivo, cliente o sitio queda fuera del Client & Site Access del rol
404
{"detail": "Not found."}
El agent_id o el id no existe
Cómo verificar que llega a la API
Desde la máquina que ejecutará la integración, llame a
GET /agents/?page=1&page_size=1con su clave, como en el ejemplo anterior. Un sobre JSON concounty un resultado demuestra que la dirección, el TLS y la clave funcionan.Llame a
GET /agents/<agent_id>/ping/para un dispositivo en línea."status": "online"demuestra que la API puede llegar al dispositivo.Haga un cambio pequeño, por ejemplo añada una nota a un dispositivo de prueba, y búsquelo en Reports & Audits › Audits con el nombre de usuario del usuario de la clave.
Errores comunes
401 en todas las llamadas
Falta la cabecera X-API-KEY o es incorrecta
Envíe la clave exactamente como la copió de Admin Center › Settings › API Keys
403 en una llamada que la consola sí le permite
La clave pertenece a otro usuario, con un rol más limitado
Compruebe el User de la clave en Admin Center › Settings › API Keys
404 en una ruta de dispositivo
Se usó el hostname en lugar del agent_id
Tome el agent_id de GET /agents/
Una llamada recibe una redirección en lugar de un resultado
Falta la / final
Termine todas las rutas en /
Unable to contact the agent
El dispositivo está sin conexión o no responde
Compruebe status en GET /agents/, o use una acción en cola, como POST /agents/actions/bulk/ u output: "forget"
No agents were found meeting the selected criteria
El destino de la acción masiva, monType y osType no seleccionan ningún dispositivo que cubra el rol
Amplíe los filtros, o revise el Client & Site Access del rol
Must select at least 1 agent
target es agents con una lista agents vacía
Envíe al menos un agent_id
Páginas relacionadas
Claves de API: cree y revoque la clave
Permisos de los roles: lo que permite cada permiso
Ejecutar un comando o un script en un dispositivo: las mismas acciones en la consola
Registro de auditoría: dónde se registran los cambios hechos por la API
Atualizado
Isto foi útil?