wulf-pulse/docs/DATTO_RMM_DEVICE_API.md

# Datto RMM Device API Documentation

## Overview

This document describes the JSON payload structure returned when requesting an individual device from the Datto RMM API v2.

## API Endpoint

```
GET https://concord-api.centrastage.net/api/v2/devices/{deviceId}
```

## Authentication

The API uses OAuth2 authentication with Bearer tokens. See the main Datto RMM client implementation for authentication details.

## Response Structure

The API returns a JSON object with an `item` property containing the device data.

### Root Response Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item` | object | Yes | The device object |

### Device Object (`item`)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `id` | number | Yes | Unique numeric identifier for the device |
| `uid` | string | Yes | Unique string identifier for the device |
| `siteId` | number | Yes | Numeric identifier of the site this device belongs to |
| `siteUid` | string | Yes | String identifier of the site this device belongs to |
| `siteName` | string | Yes | Name of the site this device belongs to |
| `deviceType` | object | Yes | Device type classification (see below) |
| `hostname` | string | Yes | Device hostname |
| `description` | string | Yes | Device description |
| `intIpAddress` | string | Yes | Internal IP address |
| `extIpAddress` | string | Yes | External IP address |
| `macAddresses` | string[] | No | List of MAC addresses associated with the device |
| `domain` | string | Yes | Domain the device belongs to |
| `manufacturer` | string | No | Device manufacturer (e.g., 'Dell', 'HP', 'Lenovo') |
| `model` | string | No | Device model |
| `serialNumber` | string | No | Device serial number |
| `lastSeen` | number | Yes | Timestamp in milliseconds when device was last seen |
| `lastLoggedInUser` | string | No | Username of the last logged in user |
| `lastReboot` | number | No | Timestamp in milliseconds of last reboot |
| `lastAuditDate` | number | No | Timestamp in milliseconds of last audit |
| `creationDate` | number | No | Timestamp in milliseconds when device was created in RMM |
| `online` | boolean | Yes | Whether the device is currently online |
| `suspended` | boolean | Yes | Whether the device is suspended |
| `deleted` | boolean | Yes | Whether the device is marked as deleted |
| `rebootRequired` | boolean | No | Whether a reboot is required |
| `a64Bit` | boolean | No | Whether the device is 64-bit architecture |
| `operatingSystem` | string | Yes | Operating system name and version |
| `cagVersion` | string | No | Version of the Datto RMM agent (CAG) |
| `displayVersion` | string | No | Display version of the operating system |
| `memory` | number | No | Total memory in MB |
| `cpuCores` | number | No | Number of CPU cores |
| `cpuName` | string | No | CPU model name |
| `diskSize` | number | No | Total disk size in GB |
| `antivirus` | object | No | Antivirus information (see below) |
| `patchManagement` | object | No | Patch management information (see below) |
| `softwareStatus` | string | No | Software status |
| `portalUrl` | string | No | URL to the device in the Datto RMM portal |
| `webRemoteUrl` | string | No | URL for web-based remote access |
| `warrantyDate` | string\|null | No | Warranty expiration date |
| `snmpEnabled` | boolean | No | Whether SNMP is enabled on the device |
| `deviceClass` | string | No | Device class classification |
| `udf` | object | No | User-defined fields (custom fields) |

### Device Type Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Device category (e.g., 'Server', 'Workstation', 'Laptop') |
| `type` | string | Yes | Specific device type |

### Antivirus Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `antivirusProduct` | string | Yes | Name of the antivirus product |
| `antivirusStatus` | string | Yes | Status of the antivirus (e.g., 'Up to date', 'Out of date') |

### Patch Management Object

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `patchStatus` | string | Yes | Overall patch status |
| `patchesApprovedPending` | number | Yes | Number of approved patches pending installation |
| `patchesNotApproved` | number | Yes | Number of patches not yet approved |
| `patchesInstalled` | number | Yes | Number of patches installed |

## Example Response

See `datto-rmm-device-example.json` for a complete example response.

## TypeScript Type Definition

The TypeScript interface is defined in `/lib/types/datto-rmm.ts`:

```typescript
export interface DattoRMMDevice {
  id: number;
  uid: string;
  siteId: number;
  siteUid: string;
  siteName: string;
  deviceType: {
    category: string;
    type: string;
  };
  hostname: string;
  description: string;
  intIpAddress: string;
  extIpAddress: string;
  macAddresses?: string[];
  domain: string;
  manufacturer?: string;
  model?: string;
  serialNumber?: string;
  lastSeen: number;
  lastLoggedInUser?: string;
  lastReboot?: number;
  lastAuditDate?: number;
  creationDate?: number;
  online: boolean;
  suspended: boolean;
  deleted: boolean;
  rebootRequired?: boolean;
  a64Bit?: boolean;
  operatingSystem: string;
  cagVersion?: string;
  displayVersion?: string;
  memory?: number;
  cpuCores?: number;
  cpuName?: string;
  diskSize?: number;
  antivirus?: {
    antivirusProduct: string;
    antivirusStatus: string;
  };
  patchManagement?: {
    patchStatus: string;
    patchesApprovedPending: number;
    patchesNotApproved: number;
    patchesInstalled: number;
  };
  softwareStatus?: string;
  portalUrl?: string;
  webRemoteUrl?: string;
  warrantyDate?: string | null;
  snmpEnabled?: boolean;
  deviceClass?: string;
  udf?: Record<string, any>;
}
```

## Usage in Code

```typescript
import { DattoRMMClient } from '@/lib/services/datto-rmm-client';

const client = new DattoRMMClient({
  apiUrl: 'https://concord-api.centrastage.net/api/v2',
  apiKey: 'your-api-key',
  apiSecret: 'your-api-secret'
});

// Get a single device by ID
const device = await client.getDeviceById('12345678');

if (device) {
  console.log(`Device: ${device.hostname}`);
  console.log(`Online: ${device.online}`);
  console.log(`OS: ${device.operatingSystem}`);
  console.log(`Memory: ${device.memory} MB`);
}
```

## Notes

- All timestamp fields are in milliseconds (Unix epoch time)
- Optional fields may not be present in the response depending on the device type and available data
- The `udf` (user-defined fields) object can contain any custom fields configured in your Datto RMM instance
- Hardware details like `manufacturer`, `model`, and `serialNumber` may require audit data to be populated
- Use the `getDeviceWithAudit()` method to fetch a device with enhanced hardware information from audit data

## Related Files

- **Type Definition**: `/lib/types/datto-rmm.ts`
- **Client Implementation**: `/lib/services/datto-rmm-client.ts`
- **JSON Schema**: `/docs/datto-rmm-device-schema.json`
- **Example Response**: `/docs/datto-rmm-device-example.json`

## API Reference

For complete Datto RMM API documentation, visit:
https://help.aem.autotask.net/en/Content/APIs/API-Home.htm