> For the complete documentation index, see [llms.txt](https://wiki.datadike.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.datadike.com/es/sonar/reference/api.md). # 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](/es/sonar/administration/settings/api-keys.md). ```bash curl -s \ -H "X-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](/es/sonar/reference/permissions.md). ## 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_id` del dispositivo, un identificador largo que devuelve `GET /agents/`. No es el hostname. * **Otros identificadores.** Los clientes, sitios, checks, tareas, scripts, alertas y actualizaciones se identifican por su `id` numé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: ```json { "count": 1250, "total_pages": 125, "next": "...", "previous": null, "results": [] } ``` | Parámetro | Qué hace | | -------------- | -------------------------------------------------------------------------------------------------------------- | | `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 | Método | Ruta | Qué hace | Permiso | | ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | GET | `/agents/` | Lista los dispositivos, paginados y filtrados como se indica arriba | List Agents | | GET | `/agents//` | Detalles completos de un dispositivo, incluidos hardware, discos, checks y campos personalizados | List Agents | | PUT | `/agents//` | 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//` | Quita el agente del dispositivo y el dispositivo de SONAR | Uninstall Agents | | GET | `/agents//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//history/` | Comandos y scripts ejecutados en el dispositivo, con sus resultados | List Agent History | | GET | `/agents//notes/` | Notas de un dispositivo | List Notes | | POST | `/agents/notes/` | Añade una nota: `{"agent_id": "...", "note": "..."}` | Manage Notes | ### Comandos, scripts y energía | Método | Ruta | Qué hace | Permiso | | ----------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------ | ------------------- | | POST | `/agents//cmd/` | Ejecuta un comando y devuelve su salida. Cuerpo más abajo | Send Command | | POST | `/agents//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//reboot/` | Reinicia ahora | Reboot Agents | | PATCH | `/agents//reboot/` | Programa un reinicio en un dispositivo Windows: `{"datetime": "2026-10-01T22:00"}` | Reboot Agents | | POST | `/agents//shutdown/` | Apaga | Reboot Agents | | POST | `/agents//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//` | Un script con su cuerpo | List Scripts | | POST, PUT, DELETE | `/scripts/`, `/scripts//` | Crea, cambia o elimina un script | Manage Scripts | Ejecutar un comando: ```json { "cmd": "ipconfig /all", "shell": "cmd", "timeout": 30, "run_as_user": false } ``` `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: ```json { "script": 42, "output": "wait", "args": [], "env_vars": [], "timeout": 90, "run_as_user": false } ``` | `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: ```json { "mode": "script", "target": "site", "site": 7, "monType": "all", "osType": "windows", "script": 42, "args": [], "env_vars": [], "timeout": 90, "run_as_user": false } ``` | Campo | Valores | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `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": ["", ...]`, `client` con `"client": `, `site` con `"site": `, 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 | Método | Ruta | Qué hace | Permiso | | -------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------- | | 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//` | Un cliente | List Clients | | PUT | `/clients//` | Cambia un cliente: `{"client": {"name": "..."}}` | Manage Clients | | DELETE | `/clients//?move_to_site=` | 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//` | Lee o cambia un sitio: `{"site": {"name": "..."}}` | List Sites / Manage Sites | | DELETE | `/clients/sites//?move_to_site=` | 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 | Método | Ruta | Qué hace | Permiso | | ------ | -------------------- | -------------------------------------------------------------------------------------- | -------------------- | | PATCH | `/alerts/` | Consulta alertas. Cuerpo más abajo | List Alerts | | GET | `/alerts//` | Una alerta | List Alerts | | PUT | `/alerts//` | `{"type": "resolve"}`, `{"type": "snooze", "snooze_days": 2}` o `{"type": "unsnooze"}` | Manage Alerts | | DELETE | `/alerts//` | 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: ```json { "timeFilter": 7, "severityFilter": ["error", "warning"], "clientFilter": [3], "resolvedFilter": false, "snoozedFilter": false } ``` `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 | Método | Ruta | Qué hace | Permiso | | ---------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------- | | GET | `/agents//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": ""` y los ajustes del check | Manage Checks | | GET, PUT, DELETE | `/checks//` | Lee, cambia o elimina un check | List Checks / Manage Checks | | POST | `/checks//run/` | Ejecuta ahora todos los checks del dispositivo | Run Checks | | POST | `/checks/client//csbulkrun/` | Ejecuta los checks en todos los dispositivos de un cliente. Use `site` para un sitio | Run Checks | | POST | `/checks//reset/` | Restablece un check a correcto. `` es el `id` dentro de `check_result` | Manage Checks | | POST | `/checks//resetall/` | Restablece todos los checks del dispositivo a correcto | Manage Checks | | PATCH | `/checks//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//`. ### Tareas automatizadas | Método | Ruta | Qué hace | Permiso | | ---------------- | --------------------------- | --------------------------------------------------------------------------------------- | ------------------------- | | GET | `/agents//tasks/` | Tareas de un dispositivo, incluidas las heredadas de políticas | List Tasks | | POST | `/tasks/` | Crea una tarea. Envíe `"agent": ""` y los ajustes de la tarea | Manage Tasks | | GET, PUT, DELETE | `/tasks//` | Lee, cambia o elimina una tarea | List Tasks / Manage Tasks | | POST | `/tasks//run/` | Ejecuta una tarea ahora. Para una tarea de política, añada `{"agent_id": ""}` | Run Tasks | Igual que con los checks, cree una tarea en la consola y léala con `GET /tasks//` para conocer los campos. ### Software | Método | Ruta | Qué hace | Permiso | | ------ | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------- | | GET | `/software//` | Software instalado en un dispositivo | List Software | | PUT | `/software//` | Pide a un dispositivo Windows una lista de software actualizada | Manage Software | | GET | `/software/chocos/` | Paquetes disponibles para instalar | List Software | | POST | `/software//` | Instala un paquete en un dispositivo Windows: `{"name": "7zip"}`. Siga el proceso en las acciones pendientes del dispositivo | Manage Software | ### Actualizaciones (Windows Update) | Método | Ruta | Qué hace | Permiso | | ------ | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | GET | `/winupdate//` | 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//scan/` | Busca actualizaciones en el dispositivo | Manage Windows Updates | | POST | `/winupdate//install/` | Instala las actualizaciones aprobadas | Manage Windows Updates | | PUT | `/winupdate//` | 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 | Método | Ruta | Qué hace | Permiso | | ------ | ------------------------------------ | ------------------------------------------------------------------------------------------ | ---------------------- | | PATCH | `/logs/audit/` | Consulta el registro de auditoría. Cuerpo más abajo | View Audit Logs | | GET | `/agents//pendingactions/` | Acciones en cola de un dispositivo, como reinicios programados e instalaciones de software | List Pending Actions | | DELETE | `/logs/pendingactions//` | Cancela una acción pendiente | Manage Pending Actions | Cuerpo de la consulta de auditoría: ```json { "pagination": { "sortBy": "entry_time", "descending": true, "page": 1, "rowsPerPage": 100 }, "timeFilter": 1, "actionFilter": ["login", "failed_login"], "userFilter": ["jdoe"] } ``` 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": }`. Mantenga `rowsPerPage` entre 25 y 1000. ## Errores | Estado | Cuerpo | Causa habitual | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | 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 1. Desde la máquina que ejecutará la integración, llame a `GET /agents/?page=1&page_size=1` con su clave, como en el ejemplo anterior. Un sobre JSON con `count` y un resultado demuestra que la dirección, el TLS y la clave funcionan. 2. Llame a `GET /agents//ping/` para un dispositivo en línea. `"status": "online"` demuestra que la API puede llegar al dispositivo. 3. 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 | Síntoma | Causa | Solución | | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | 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](/es/sonar/administration/settings/api-keys.md): cree y revoque la clave * [Permisos de los roles](/es/sonar/reference/permissions.md): lo que permite cada permiso * [Ejecutar un comando o un script en un dispositivo](/es/sonar/administration/automation/run-commands-and-scripts.md): las mismas acciones en la consola * [Registro de auditoría](/es/sonar/administration/audit/audit-trail.md): dónde se registran los cambios hechos por la API