lorentz/wulf-pulse
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions

Add Datto RMM device API documentation

Browse source
This commit is contained in:
root 2025-12-04 23:16:01 -05:00
parent 6eee14f8af
commit df333348f6
3 changed files with 506 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

201
docs/DATTO_RMM_DEVICE_API.md Normal file
View file

@ -0,0 +1,201 @@
# 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

63
docs/datto-rmm-device-example.json Normal file
View file

@ -0,0 +1,63 @@
{
"item": {
"id": 12345678,
"uid": "abc123def456",
"siteId": 98765,
"siteUid": "site-uid-123",
"siteName": "Acme Corporation",
"deviceType": {
"category": "Workstation",
"type": "Desktop"
},
"hostname": "DESKTOP-ABC123",
"description": "John Doe's Workstation",
"intIpAddress": "192.168.1.100",
"extIpAddress": "203.0.113.45",
"macAddresses": [
"00:1A:2B:3C:4D:5E",
"00:1A:2B:3C:4D:5F"
],
"domain": "acme.local",
"manufacturer": "Dell Inc.",
"model": "OptiPlex 7090",
"serialNumber": "ABC123XYZ789",
"lastSeen": 1701532800000,
"lastLoggedInUser": "jdoe",
"lastReboot": 1701446400000,
"lastAuditDate": 1701518400000,
"creationDate": 1640995200000,
"online": true,
"suspended": false,
"deleted": false,
"rebootRequired": false,
"a64Bit": true,
"operatingSystem": "Windows 11 Pro",
"cagVersion": "2.5.1.123",
"displayVersion": "22H2",
"memory": 16384,
"cpuCores": 8,
"cpuName": "Intel(R) Core(TM) i7-11700 @ 2.50GHz",
"diskSize": 512,
"antivirus": {
"antivirusProduct": "Windows Defender",
"antivirusStatus": "Up to date"
},
"patchManagement": {
"patchStatus": "Current",
"patchesApprovedPending": 2,
"patchesNotApproved": 5,
"patchesInstalled": 145
},
"softwareStatus": "Compliant",
"portalUrl": "https://concord.centrastage.net/csm/device/12345678",
"webRemoteUrl": "https://concord.centrastage.net/remote/12345678",
"warrantyDate": "2026-12-31",
"snmpEnabled": false,
"deviceClass": "Workstation",
"udf": {
"customField1": "Value1",
"customField2": "Value2",
"department": "Engineering"
}
}
}

242
docs/datto-rmm-device-schema.json Normal file
View file

@ -0,0 +1,242 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Datto RMM Device Response Schema",
"description": "JSON schema for the response when requesting an individual device from Datto RMM API v2",
"type": "object",
"properties": {
"item": {
"type": "object",
"description": "The device object returned by the API",
"properties": {
"id": {
"type": "number",
"description": "Unique numeric identifier for the device"
},
"uid": {
"type": "string",
"description": "Unique string identifier for the device"
},
"siteId": {
"type": "number",
"description": "Numeric identifier of the site this device belongs to"
},
"siteUid": {
"type": "string",
"description": "String identifier of the site this device belongs to"
},
"siteName": {
"type": "string",
"description": "Name of the site this device belongs to"
},
"deviceType": {
"type": "object",
"description": "Device type classification",
"properties": {
"category": {
"type": "string",
"description": "Device category (e.g., 'Server', 'Workstation', 'Laptop')"
},
"type": {
"type": "string",
"description": "Specific device type"
}
},
"required": ["category", "type"]
},
"hostname": {
"type": "string",
"description": "Device hostname"
},
"description": {
"type": "string",
"description": "Device description"
},
"intIpAddress": {
"type": "string",
"description": "Internal IP address"
},
"extIpAddress": {
"type": "string",
"description": "External IP address"
},
"macAddresses": {
"type": "array",
"description": "List of MAC addresses associated with the device",
"items": {
"type": "string"
}
},
"domain": {
"type": "string",
"description": "Domain the device belongs to"
},
"manufacturer": {
"type": "string",
"description": "Device manufacturer (e.g., 'Dell', 'HP', 'Lenovo')"
},
"model": {
"type": "string",
"description": "Device model"
},
"serialNumber": {
"type": "string",
"description": "Device serial number"
},
"lastSeen": {
"type": "number",
"description": "Timestamp in milliseconds when device was last seen"
},
"lastLoggedInUser": {
"type": "string",
"description": "Username of the last logged in user"
},
"lastReboot": {
"type": "number",
"description": "Timestamp in milliseconds of last reboot"
},
"lastAuditDate": {
"type": "number",
"description": "Timestamp in milliseconds of last audit"
},
"creationDate": {
"type": "number",
"description": "Timestamp in milliseconds when device was created in RMM"
},
"online": {
"type": "boolean",
"description": "Whether the device is currently online"
},
"suspended": {
"type": "boolean",
"description": "Whether the device is suspended"
},
"deleted": {
"type": "boolean",
"description": "Whether the device is marked as deleted"
},
"rebootRequired": {
"type": "boolean",
"description": "Whether a reboot is required"
},
"a64Bit": {
"type": "boolean",
"description": "Whether the device is 64-bit architecture"
},
"operatingSystem": {
"type": "string",
"description": "Operating system name and version"
},
"cagVersion": {
"type": "string",
"description": "Version of the Datto RMM agent (CAG)"
},
"displayVersion": {
"type": "string",
"description": "Display version of the operating system"
},
"memory": {
"type": "number",
"description": "Total memory in MB"
},
"cpuCores": {
"type": "number",
"description": "Number of CPU cores"
},
"cpuName": {
"type": "string",
"description": "CPU model name"
},
"diskSize": {
"type": "number",
"description": "Total disk size in GB"
},
"antivirus": {
"type": "object",
"description": "Antivirus information",
"properties": {
"antivirusProduct": {
"type": "string",
"description": "Name of the antivirus product"
},
"antivirusStatus": {
"type": "string",
"description": "Status of the antivirus (e.g., 'Up to date', 'Out of date')"
}
},
"required": ["antivirusProduct", "antivirusStatus"]
},
"patchManagement": {
"type": "object",
"description": "Patch management information",
"properties": {
"patchStatus": {
"type": "string",
"description": "Overall patch status"
},
"patchesApprovedPending": {
"type": "number",
"description": "Number of approved patches pending installation"
},
"patchesNotApproved": {
"type": "number",
"description": "Number of patches not yet approved"
},
"patchesInstalled": {
"type": "number",
"description": "Number of patches installed"
}
},
"required": ["patchStatus", "patchesApprovedPending", "patchesNotApproved", "patchesInstalled"]
},
"softwareStatus": {
"type": "string",
"description": "Software status"
},
"portalUrl": {
"type": "string",
"description": "URL to the device in the Datto RMM portal"
},
"webRemoteUrl": {
"type": "string",
"description": "URL for web-based remote access"
},
"warrantyDate": {
"type": ["string", "null"],
"description": "Warranty expiration date"
},
"snmpEnabled": {
"type": "boolean",
"description": "Whether SNMP is enabled on the device"
},
"deviceClass": {
"type": "string",
"description": "Device class classification"
},
"udf": {
"type": "object",
"description": "User-defined fields (custom fields)",
"additionalProperties": true
}
},
"required": [
"id",
"uid",
"siteId",
"siteUid",
"siteName",
"deviceType",
"hostname",
"description",
"intIpAddress",
"extIpAddress",
"domain",
"lastSeen",
"online",
"suspended",
"deleted",
"operatingSystem"
]
}
},
"required": ["item"]
}