Skip to content

Commit c1c83e6

Browse files
james-s-andersonjames-s-anderson
committed
Add change tracker agents/register endpoint docs
1 parent 5a6d976 commit c1c83e6

File tree

1 file changed

+197
-0
lines changed

1 file changed

+197
-0
lines changed

‎docs/changetracker/8.1/integration/api/register-agents.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: "Register Agents"
3+
description: "Agent Registration API for managing device agents in ChangeTracker"
4+
sidebar_position: 11
5+
---
6+
7+
# Register Agents
8+
9+
## Overview
10+
11+
The Agent Registration API allows you to register and manage agents with the ChangeTracker system. This API provides endpoints for registering new agents, which can be either direct agents installed on devices or proxied devices accessed through another agent. The API handles various device types including servers, desktops, network devices, and databases.
12+
13+
Agents are identified by a unique AgentDevice ID and include various parameters such as device name, host type, operating system details, and network information. The API requires authentication and the `DeviceRegister` permission to perform operations.
14+
15+
## Endpoints
16+
17+
### Register Agent
18+
19+
Registers the details of an Agent with the system.
20+
21+
**HTTP Request**
22+
```
23+
POST /agents/register
24+
```
25+
26+
**Authentication**
27+
Requires authentication and the `DeviceRegister` permission.
28+
29+
**Request Body**
30+
```json
31+
{
32+
"AgentName": "string",
33+
"CanProxy": false,
34+
"CredentialKey": "string",
35+
"DeviceName": "string",
36+
"DeviceType": "Server",
37+
"GroupNames": ["Group1", "Group2"],
38+
"HostName": "string",
39+
"HostType": "Windows",
40+
"MacAddresses": "string",
41+
"IPv4": "192.168.1.100",
42+
"IPv6": "string",
43+
"LegacyHubId": "string",
44+
"DiscoveryId": "string",
45+
"DiscoveryTaskId": "string",
46+
"OnlineDetection": "Ping",
47+
"Os": "Windows Server 2019",
48+
"KnownOsName": "Windows Server",
49+
"OsUserSpecified": "string",
50+
"PollPeriodSeconds": 300,
51+
"ProxiedByAgentId": "string",
52+
"Registered": false,
53+
"UniqueId": "string",
54+
"Version": 0
55+
}
56+
```
57+
58+
**Parameters**
59+
| Parameter | Type | Required | Description |
60+
|-----------|------|----------|-------------|
61+
| AgentName | string | No | The name of the agent |
62+
| CanProxy | boolean | No | Specifies whether the agent can proxy connections to other devices |
63+
| CredentialKey | string | No | Specifies the credential key (only allowed for proxied devices) |
64+
| DeviceName | string | No | Specifies the device name |
65+
| DeviceType | enum | No | Type of device (Unknown, Server, Desktop, Network, Database) |
66+
| GroupNames | array | No | Specifies the group names (only allowed for proxied devices) |
67+
| HostName | string | No | Specifies the host name or IP address used for agentless access |
68+
| HostType | enum | No | Specifies the host type (Unknown, Unix, Windows, Network, Database, Cloud, ESX, Splunk) |
69+
| MacAddresses | string | No | Specifies the MAC addresses |
70+
| IPv4 | string | No | Specifies the IPv4 address |
71+
| IPv6 | string | No | Specifies the IPv6 address |
72+
| LegacyHubId | string | No | Specifies the legacy hub ID |
73+
| DiscoveryId | string | No | Specifies the internal discovery-based ID |
74+
| DiscoveryTaskId | string | No | Specifies the internal discovery task ID |
75+
| OnlineDetection | enum | No | Specifies the method to use when detecting if a proxied device is online (None, Ping, TcpConnect) |
76+
| Os | string | No | Specifies the Operating System full description as reported by the device |
77+
| KnownOsName | string | No | Specifies the Operating System from the list of known OS names |
78+
| OsUserSpecified | string | No | Specifies the operating system as entered by the user (overrides discovered OS in UI) |
79+
| PollPeriodSeconds | integer | No | Specifies the poll period in seconds |
80+
| ProxiedByAgentId | string | No | Specifies the agent ID of the proxy agent this device will be proxied by |
81+
| Registered | boolean | No | Specifies whether the agent is registered |
82+
| UniqueId | string | No | Specifies a value uniquely identifying the agent independent of name or agent ID |
83+
| Version | integer | No | Specifies the request version |
84+
85+
**Response**
86+
Returns an Agent object with the following properties:
87+
88+
```json
89+
{
90+
"ModelVersion": 0,
91+
"AgentDevice": {
92+
"AgentId": "string",
93+
"DeviceId": "string"
94+
},
95+
"Version": "string",
96+
"Name": "string",
97+
"DeviceName": "string",
98+
"FullyQualifiedDomainName": "string",
99+
"DeviceType": "Server",
100+
"HostType": "Windows",
101+
"Os": "Windows Server 2019",
102+
"OsUserSpecified": "string",
103+
"KnownOsName": "Windows Server",
104+
"OsVariant": "64 bit version",
105+
"Registered": true,
106+
"Deleted": false,
107+
"PollPeriodSeconds": 300,
108+
"LegacyId": "string",
109+
"DiscoveryId": "string",
110+
"DiscoveryTaskId": "string",
111+
"HostName": "string",
112+
"MacAddresses": "string",
113+
"IPv4": "192.168.1.100",
114+
"IPv6": "string",
115+
"LastPollUtc": "2025-08-21T10:23:32.0000000Z",
116+
"NextPollUtc": "2025-08-21T10:28:32.0000000Z",
117+
"MembershipChangeTimeUtc": "2025-08-21T10:23:32.0000000Z",
118+
"OnlineStatus": "Online",
119+
"DiagnosticModeEnabled": false,
120+
"EventBlockEnabled": false,
121+
"BaselineSendEnabled": true,
122+
"OnlineDetection": "Ping",
123+
"PingTimeoutSeconds": 5,
124+
"TcpConnectPort": 0,
125+
"CanProxy": false,
126+
"UniqueId": "string",
127+
"IsTestAgent": false,
128+
"RecentActivity": {
129+
"AgentDeviceId": "string",
130+
"LastUpdatedUtc": "2025-08-21T10:23:32.0000000Z",
131+
"ConfigDateUtc": "2025-08-21T10:23:32.0000000Z",
132+
"LoginName": "string",
133+
"ProcessId": 0
134+
},
135+
"SkipConfigCheckUntilUtc": "2025-08-21T10:23:32.0000000Z",
136+
"AgentType": "NetCore",
137+
"IsBlockingRegistrationBy": "string",
138+
"PublicKeyStringsInUse": "string"
139+
}
140+
```
141+
142+
## Device Types
143+
144+
The following device types are supported:
145+
146+
| Type | Description |
147+
|------|-------------|
148+
| Server | Server device |
149+
| Desktop | Desktop computer |
150+
| Network | Network device |
151+
| Database | Database server |
152+
153+
## Host Types
154+
155+
The following host types are supported:
156+
157+
| Type | Description |
158+
|------|-------------|
159+
| Unix | Unix-based system |
160+
| Windows | Windows-based system |
161+
| Network | Network device |
162+
| Database | Database server |
163+
| Cloud | Cloud service |
164+
| ESX | VMware ESX/ESXi server |
165+
| Splunk | Splunk server |
166+
167+
## Online Detection Methods
168+
169+
The following online detection methods are available:
170+
171+
| Method | Description |
172+
|--------|-------------|
173+
| None | No online detection |
174+
| Ping | Use ICMP ping to detect if device is online |
175+
| TcpConnect | Use TCP connection to detect if device is online |
176+
177+
## Agent Types
178+
179+
The following agent types are supported:
180+
181+
| Type | Description |
182+
|------|-------------|
183+
| Unknown | Unknown agent type |
184+
| NetDesktop | .NET Desktop agent |
185+
| Mono | Mono-based agent |
186+
| NetCore | .NET Core agent |
187+
| ExpressAgent | Express agent |
188+
189+
## Device Online Status
190+
191+
The following online statuses are available:
192+
193+
| Status | Description |
194+
|--------|-------------|
195+
| WaitingForContact | Agent has not yet contacted the server |
196+
| Online | Agent is online and communicating with the server |
197+
| Offline | Agent is offline or not responding |

0 commit comments

Comments
 (0)