wulfclaw/DATTO_RMM_OPENCLAW_SKILL.md

# Datto RMM — OpenClaw Read-Only API Skill

> **Purpose:** Query Datto RMM data (devices, sites, alerts) from the Pulse platform via authenticated read-only OpenClaw API endpoints. All data is sourced from Pulse's local PostgreSQL DB by default, with an option to fetch live from the Datto RMM API.

## Base URL

```
https://pulse.wulfconsulting.cloud
```

## Authentication

Every request requires the `x-openclaw-key` header:

```http
x-openclaw-key: <OPENCLAW_API_KEY>
```

Missing or invalid key → `401 Unauthorized`.

---

## Data Source Behaviour

| Parameter | Behaviour |
|---|---|
| *(default)* | Queries Pulse's local DB — fast, no Datto rate limits, data is as fresh as the last sync |
| `?live=true` | Proxies directly to the live Datto RMM API — always current but slower |

Every response includes `"source": "db"` or `"source": "live"` so you always know data freshness. DB responses also include `synced_at` where available.

---

## Endpoints

### 1. List Sites

```
GET /api/openclaw/datto-rmm/sites
GET /api/openclaw/datto-rmm/sites?live=true
```

Returns all Datto RMM sites linked to Autotask companies.

**Response:**
```json
{
  "data": [
    {
      "id": 376835,
      "uid": "68431d2c-8327-4d86-a05b-b60d4e7f793e",
      "name": "Acme Corp",
      "autotask_company_id": 29683001,
      "autotask_company_name": "Acme Corp",
      "number_of_devices": 42,
      "number_of_online_devices": 38,
      "number_of_offline_devices": 4,
      "portal_url": "https://concord.centrastage.net/csm/...",
      "synced_at": "2026-03-21T20:00:00Z"
    }
  ],
  "total": 87,
  "source": "db"
}
```

**Key fields:**
- `uid` — Datto RMM site UID (use for device filtering)
- `autotask_company_id` — links to Autotask `companies.id` in Pulse DB
- `number_of_online_devices` / `number_of_offline_devices` — counts from last sync

---

### 2. List Devices

```
GET /api/openclaw/datto-rmm/devices
```

**Query parameters:**

| Param | Type | Description |
|---|---|---|
| `siteUid` | string | Filter by Datto RMM site UID |
| `online` | boolean | `true` / `false` — filter by online status |
| `deleted` | boolean | `true` / `false` — include/exclude deleted devices |
| `page` | int | Page number (default: 1) |
| `limit` | int | Items per page (default: 100, max: 500) |
| `live` | boolean | Use live Datto API instead of DB |

**Response:**
```json
{
  "data": [
    {
      "uid": "abc123-...",
      "hostname": "WS-SMITH-01",
      "site_uid": "68431d2c-...",
      "site_name": "Acme Corp",
      "device_type_category": "Desktop",
      "device_type": "Windows Workstation",
      "operating_system": "Windows 11 Pro",
      "domain": "acme.local",
      "int_ip_address": "10.1.1.50",
      "ext_ip_address": "203.0.113.5",
      "online": true,
      "last_seen": "2026-03-21T19:45:00Z",
      "last_logged_in_user": "jsmith",
      "antivirus_product": "Windows Defender",
      "antivirus_status": "Fully Protected",
      "patch_status": "Fully Patched",
      "patches_approved_pending": 0,
      "reboot_required": false,
      "udf": { "udf1": "...", "udf2": "..." }
    }
  ],
  "total": 3597,
  "page": 1,
  "limit": 100,
  "source": "db"
}
```

**Key fields:**
- `uid` — Datto RMM device UID (also stored as `configuration_items.reference_number` in Autotask)
- `device_type_category` — Server, Desktop, Laptop, Network Device
- `antivirus_status` — "Fully Protected", "At Risk", etc.
- `patch_status` — "Fully Patched", "Patches Available", "Reboot Required", etc.
- `udf` — JSONB object with up to 30 user-defined fields

---

### 3. Get Single Device

```
GET /api/openclaw/datto-rmm/devices/{uid}
GET /api/openclaw/datto-rmm/devices/{uid}?live=true
```

Returns full device record by Datto RMM UID.

**Response:**
```json
{
  "data": { /* same fields as list, plus: a64_bit, snmp_enabled, network_probe, software_status, warranty_date, cag_version, display_version, web_remote_url */ },
  "source": "db"
}
```

Returns `404` if not found.

---

### 4. Get Device Audit Data

```
GET /api/openclaw/datto-rmm/devices/{uid}/audit
```

> **Always live** — fetches real-time audit data from Datto RMM API. No `?live=true` needed.

Returns detailed hardware/software audit including:
- CPU, RAM, disk, BIOS
- Network adapters
- Installed software list
- Hardware inventory

Returns `404` if device has no audit data.

---

### 5. List Alerts

```
GET /api/openclaw/datto-rmm/alerts
```

**Query parameters:**

| Param | Type | Description |
|---|---|---|
| `resolved` | boolean | `true` = resolved only, `false` = open only, omit = all |
| `siteUid` | string | Filter by site UID |
| `deviceUid` | string | Filter by device UID |
| `limit` | int | Max results (default: 200, max: 1000) |
| `live` | boolean | Use live Datto API |

**Response:**
```json
{
  "data": [
    {
      "alert_uid": "a1b2c3...",
      "alert_category": "Patch Management",
      "alert_type": "Patch Not Installed",
      "alert_message_en": "Critical patches pending",
      "device_uid": "abc123-...",
      "device_hostname": "WS-SMITH-01",
      "device_os": "Windows 11 Pro",
      "site_uid": "68431d2c-...",
      "site_name": "Acme Corp",
      "resolved": false,
      "muted": false,
      "ticket_number": "T20240315.0042",
      "timestamp": "2026-03-20T14:22:00Z"
    }
  ],
  "total": 847,
  "source": "db"
}
```

**Key fields:**
- `alert_category` — Patch Management, Antivirus, Performance, Connectivity, etc.
- `ticket_number` — Autotask ticket number if one was auto-created
- `resolved` — false = currently active alert

---

### 6. List Open Alerts (Shorthand)

```
GET /api/openclaw/datto-rmm/alerts/open
GET /api/openclaw/datto-rmm/alerts/open?siteUid=68431d2c-...
GET /api/openclaw/datto-rmm/alerts/open?live=true
```

Equivalent to `GET /alerts?resolved=false`. Same parameters and response shape as `/alerts` (excluding `resolved` filter since it's always `false`).

---

## Common Usage Patterns

### Get all offline devices across all sites
```
GET /api/openclaw/datto-rmm/devices?online=false&limit=500
```

### Get open alerts for a specific client
1. `GET /api/openclaw/datto-rmm/sites` → find the site UID for the client
2. `GET /api/openclaw/datto-rmm/alerts/open?siteUid={uid}`

### Check patch status for all devices at a site
```
GET /api/openclaw/datto-rmm/devices?siteUid={uid}&limit=500
```
Then filter `data` where `patch_status != "Fully Patched"`.

### Deep-dive a specific device
1. `GET /api/openclaw/datto-rmm/devices/{uid}` — base info from DB
2. `GET /api/openclaw/datto-rmm/devices/{uid}/audit` — live hardware/software detail

### Force fresh data (bypass DB cache)
```
GET /api/openclaw/datto-rmm/devices?live=true&siteUid={uid}
```

---

## Linking to Autotask / Pulse DB

| RMM field | Pulse DB join |
|---|---|
| `datto_rmm_sites.autotask_company_id` | `companies.id` |
| `datto_rmm_devices.site_id` | `datto_rmm_sites.id` |
| `datto_rmm_alerts.device_uid` | `datto_rmm_devices.uid` |
| `datto_rmm_devices.uid` | `configuration_items.reference_number` (sometimes) |
| `datto_rmm_alerts.ticket_number` | `tickets.ticket_number` |

---

## Error Responses

| HTTP | Meaning |
|---|---|
| 401 | Missing or invalid `x-openclaw-key` |
| 404 | Device/resource not found |
| 500 | Internal error (DB or Datto API) — check `error` field |

---

## Notes

- **Sync freshness:** DB data is updated by scheduled Datto RMM syncs (typically every hour). Check `synced_at` in site/device responses for last sync time.
- **Device UIDs:** Datto `uid` is a UUID string. Do not confuse with `id` (integer DB primary key).
- **UDFs:** `udf` is a JSONB field with up to 30 user-defined fields (`udf1`–`udf30`). Field meaning varies per client configuration.
- **Alert `site_uid`** is a text field matching `datto_rmm_sites.uid` (not the integer `id`).
- **Audit endpoint** always makes a live call to Datto RMM — expect 1–3s latency.