Add Datto RMM device API documentation
This commit is contained in:
root
parent
6eee14f8af
commit
df333348f6
3 changed files with 506 additions and 0 deletions
201
docs/DATTO_RMM_DEVICE_API.md
Normal file
201
docs/DATTO_RMM_DEVICE_API.md
Normal 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
63
docs/datto-rmm-device-example.json
Normal 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
242
docs/datto-rmm-device-schema.json
Normal 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"]
|
||||||
|
}
|
||||||
Loading…
Add table
Add a link
Reference in a new issue