SimpleHelp Integration API
Version 1.0
The SimpleHelp API is a web-based HTTP API that clients can use to query state in the SimpleHelp server and modify certain configuration settings. The API is REST-like. Each HTTP request contains all the data required to complete that request.
The SimpleHelp API endpoint is:
https://host:port/api/v1/query
where:
- host - the hostname of your SimpleHelp server
- port - the port to connect on
- query - the query to process on the server
Each API request to the API endpoint may optionally include POST data sent from the client to the server. The server will then respond with an HTTP return code and some return data. The post data and return data are JSON formatted.
API requests must be made over HTTPS. Non-HTTPS requests are rejected unless the server is running as a development server.
Authorisation
An API token is included in every query to authorise the request. The API token is server-specific and can be generated in the Administration tab of the Technician Console. The preferred method is to specify the API token using the Authorization HTTP header:
Authorization: Bearer <api_token>
For compatibility with older integrations, the API token can also be specified as part of the requesting URL:
https://host:port/api/v1/api_token/query
API tokens have their own permission set. If the token is valid but does not grant permission for the requested action, the server returns an API error response.
Request Options
Most API requests use POST data encoded as JSON. Include prettyPrint: true in the posted JSON to format the response JSON for readability.
List endpoints that support sorting accept sortBy. The value must be the name of a response object field. Prefix the field name with - to sort descending, for example -name.
API Errors and Return Codes
SimpleHelp uses HTTP return codes to indicate whether a request was successful or not. Return codes can be split into three groups:
- 200s - Success.
- 400s - Failure to process the requested query given the post data and API token.
- 500s - Server failure.
Certain API calls, and API failures, will return an API response with details about whether the call succeeded and some reason for a failure.
API Response Object
| X | X |
|---|---|
| success Boolean |
true if the request was successful, and false otherwise. |
| reason String |
if success is false, a short description why the request failed. |
Technician Queries
Technician queries manage the set of technicians configured in the SimpleHelp server. A Technician Object contains attributes specific to each technician account.
Technician Object
| X | X |
|---|---|
| uniqueID integer |
An internal unique identifier for this technician. |
| displayName String |
The technician’s display name. |
| username String |
The technician’s username, which must be unique. |
| emailAddress String |
An email address for this technician. |
| allowLocallyAuthenticatedLogins Boolean |
true if this technician can login using their account password. |
| enabled Boolean |
true if this technician’s account is currently enabled. |
| enabledUntilTime Long |
The time until which this technician account is enabled, in milliseconds. |
| groupIDs Integer Array |
An integer array of Technician Group IDs indicating which groups this technician is a member of. |
List Technicians
/technicians/list
Request the list of technician accounts from the server
curl [SERVER]/technicians/list \
-X POST \
-H "Content-Type: application/json"
Return a JSON array of Technician Objects detailing all technician accounts configured in the SimpleHelp server.
POST Data Attributes
| X | X |
|---|---|
| sortBy String |
The Technician Object field to sort by. Prefix with - to sort descending. |
Response
| X | X |
|---|---|
| Technician Object Array | A JSON array of Technician Objects representing the technician accounts in the server. |
Create a New Technician
/technicians/new
Create a technician account
curl [SERVER]/technicians/new \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser", emailAddress:"[email protected]}}'
Create a new technician account in the SimpleHelp server.
POST Data Attributes
| X | X |
|---|---|
| technician Technician Object |
A JSON Technician Object detailing the account to create. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Retrieve a Technician
/technicians/get
Retrieve a technician account by username
curl [SERVER]/technicians/get \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser"}}'
Retrieve a technician account by uniqueID or by username.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified lookup a technician by this uniqueID. |
| username String |
If specified lookup a technician by this username. |
| technician Technician Object |
If specified lookup a technician using the username attribute of this technician object. |
Response Data
| X | X |
|---|---|
| Technician Object | A technician object representing this technician account. |
Update a Technician
/technicians/set
Set the display name for a technician
curl [SERVER]/technicians/set \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser", displayName: "New Name"}}'
Update one or more technician account attributes.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified update the technician account with this uniqueID. |
| username String |
If specified lookup a technician by this username. |
| technician Technician Object |
A technician object with one or more attributes that will be set for this technician account. If the uniqueID is not specified update the technician account using the username attribute of this technician object. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Remove a Technician
/technicians/remove
Remove a technician account
curl [SERVER]/technicians/remove \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser"}}'
Remove a technician by uniqueID or by username.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified remove a technician with this uniqueID. |
| username String |
If specified lookup a technician by this username. |
| technician Technician Object |
If specified remove a technician using the username attribute of this technician object. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Set a Technician Password
/technicians/password/set
Set a password to abcd1234
curl [SERVER]/technicians/password/set \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser"}, password:"abcd1234"}'
Set the password of a technician account.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified set the password for a technician with this uniqueID. |
| username String |
If specified lookup a technician by this username. |
| technician Technician Object |
If specified set the password for a technician using the username attribute of this technician object. |
| password String |
The new password to set. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Reset a Technician TOTP Key
/technicians/totp/remove
Remove an OTP key for a technician
curl [SERVER]/technicians/totp/remove \
-X POST \
-H "Content-Type: application/json"
-d '{technician: {username: "testuser"}}'
Remove the TOTP key for a technician account. Technicians will be prompted to reconfigure their app-based authentication on next login.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified remove the TOTP key for a technician with this uniqueID. |
| username String |
If specified lookup a technician by this username. |
| technician Technician Object |
If specified remove the TOTP key for a technician using the username attribute of this technician object. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Technician Group Queries
Technician Group queries can be used to manage the set of Technician Groups in the SimpleHelp server. The following JSON object details the attributes in a Technician Group Object.
Technician Group Object
| X | X |
|---|---|
| uniqueID Integer |
An internal unique identifier for this technician group. |
| name String |
The group name. |
| allowAnonymousLogins Boolean |
true if this group allows logins of technicians with no SimpleHelp technician account. |
| max_groupShSessions Integer |
The maximum number of support sessions this group can use. |
| max_groupSgSessions Integer |
The maximum number of access sessions this group can use. |
| max_userShSessions Integer |
The maximum number of support sessions a technician in this group can use. |
| max_userSgSessions Integer |
The maximum number of access sessions a technician in this group can use. |
| maxFileSize Long |
The maximum file size that can be transferred in bytes. |
| requestAccessTimeout Long |
The timeout in milliseconds for request access requests. A timeout of 0 means no timeout. |
| inactivityTimeout Long |
The session inactivity timeout, in milliseconds. |
| inactivityLockout Long |
The session inactivity lockout duration, in milliseconds. |
| consoleTimeout Long |
The Technician Console inactivity timeout, in milliseconds. |
| consoleLockout Long |
The Technician Console inactivity lockout duration, in milliseconds. |
| groupSpecificHostname String |
The server hostname specific to users of this group. |
| defaultSgServiceName String |
The default Remote Access Service name for users of this group. |
| videoPassword String |
The password required for recordings created by users in this group. |
| sessionSpeedLimitKbps Integer |
The bandwidth limit imposed on technicians in this group. A limit of 0 means no limit. |
| fpsDelay Long |
The frame per second delay, in milliseconds, imposed on users in this group. The resulting frames per second can be calculated as 1000/fpsDelay. |
| adSettings LDAP Settings Object |
An LDAP Settings Object describing the Active Directory authentication settings for this group. |
| ldapSettings LDAP Settings Object |
A LDAP Settings Object describing the LDAP authentication settings for this group. |
| mfaSettings MFA Settings Object |
A MFA Settings Object describing the configured group multifactor authentication. |
LDAP Settings Object
| X | X |
|---|---|
| enabled Boolean |
Set to true if LDAP authentication is enabled. |
| advanced Boolean |
Set to true if advanced LDAP settings are specified. |
| baseDN String |
The baseDN to use when querying the LDAP server. |
| filter String |
The advanced search filter to use when querying the LDAP server. |
| memberOfGroups String Array |
The directory groups that members of this Technician Group will be authenticated with. |
| attributes Boolean |
Set to true when configuring LDAP attribute filters. |
| filters Attribute Filter Object Array |
Attribute filters used when attributes is true. |
Attribute Filter Object
| X | X |
|---|---|
| key String |
The LDAP attribute name. |
| operation String |
One of !=, not equals, contains, !contains, or an equality operation. |
| value String |
The value to compare against. |
MFA Settings Object
| X | X |
|---|---|
| email Boolean |
Set to true if email-based multifactor authentication is enabled. |
| app Boolean |
Set to true if app-based multifactor authentication is enabled. |
| emailCodeLength Integer |
The length of the authentication code sent to users. |
| emailSubject String |
The template email subject that is sent to users when email-based multifactor authentication is required. |
| emailBody String |
The template email body that is sent to users when email-based multifactor authentication is required. |
| rememberMachine Boolean |
Set to true if technicians are allowed to prevent future multifactor requests once authenticated. |
List Groups
/groups/list
Return all the Technician Groups
curl [SERVER]/groups/list \
-X POST \
-H "Content-Type: application/json"
Return a JSON array of Technician Group Objects detailing all technician groups configured in the SimpleHelp server.
POST Data Attributes
| X | X |
|---|---|
| sortBy String |
The Technician Group Object field to sort by. Prefix with - to sort descending. |
Response Data
| X | X |
|---|---|
| Technician Group Object Array | A JSON array of Technician Group Objects representing the groups in the server. |
Create a Technician Group
/groups/new
Create a new group called TechGroup
curl [SERVER]/groups/new \
-X POST \
-H "Content-Type: application/json"
-d '{group: {name: "TechGroup"}}'
Create a new Technician Group in the SimpleHelp server.
POST Data Attributes
| X | X |
|---|---|
| group Technician Group Object |
A JSON Technician Group Object detailing the group to create. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Retrieving a Technician Group
/groups/get
Retrieve a group by name
curl [SERVER]/groups/get \
-X POST \
-H "Content-Type: application/json"
-d '{group: {name: "TechGroup"}}'
Retrieve the details of a Technician Group by uniqueID or by group name.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified retrieve details of the group with this uniqueID. |
| group Technician Group Object |
If specified lookup a group using the name attribute of this Technician Group object. |
Response Data
| X | X |
|---|---|
| Technician Group Object | A technician group object representing this group. |
Updating a Technician Group
/groups/set
Set the name of a group with ID 1234
curl [SERVER]/groups/set \
-X POST \
-H "Content-Type: application/json"
-d '{uniqueID: 1234, group: {name: "TechGroup"}}'
Update one or more group attributes.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified set the attributes on the group with this uniqueID. |
| group Technician Group Object |
A technician group object with one or more attributes that will be set for this group. If the uniqueID is not specified update the group using the name attribute of this technician group object. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Removing a Technician Group
/groups/remove
Remove the technician group with ID 1234
curl [SERVER]/groups/remove \
-X POST \
-H "Content-Type: application/json"
-d '{uniqueID: 1234}'
Remove a group by unique ID or by group name.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified set the attributes on the group with this uniqueID. |
| group Technician Group Object |
If specified lookup a group using the name attribute of this Technician Group object. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetching Group Permissions
/groups/permissions/get
Retrieve the permissions for group with ID 1234
curl [SERVER]/groups/permissions/get \
-X POST \
-H "Content-Type: application/json"
-d '{uniqueID: 1234}'
Retrieve the permissions for a particular Technician Group.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified fetch the permissions for the group with this uniqueID. |
| uniqueIDs Integer Array |
If specified fetch the permissions for each group in this array. |
| group Technician Group Object |
If specified lookup a group using the name attribute of this Technician Group object and retrieve the permissions for this group. |
Response Data
| X | X |
|---|---|
| Map (String > Boolean) | Permissions are returned as a Map of permissions names associated with Boolean values. |
Setting Group Permissions
/groups/permissions/set
Set the canRunTools permission to
truefor group with ID 1234
curl [SERVER]/groups/permissions/set \
-X POST \
-H "Content-Type: application/json"
-d '{group: {uniqueID: 1234, permissions: {canRunTools: true}}}'
Set one or more permissions for a particular Technician Group.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
If specified fetch the permissions for the group with this uniqueID. |
| uniqueIDs Integer Array |
If specified set the permissions for each group in this array. |
| group Technician Group Object |
If specified lookup a group using the name attribute of this Technician Group object and set the permissions for this group. The permissions are specified as permissions within group. |
Technician and Group Filter Queries
Filter queries manage the customer and machine filters applied to a technician account or a technician group. The endpoints are available below both /technicians/filters and /groups/filters.
Technician filter requests must identify the technician using uniqueID, username, or a Technician Object with uniqueID or username. Group filter requests must identify the group using uniqueID or a Technician Group Object with uniqueID or name.
Filter Object
| X | X |
|---|---|
| isShow Boolean |
Whether matching items are shown (true) or hidden (false). |
| fieldNameToFilter String |
The customer or machine field to filter. |
| checkAction Integer |
The comparison action used by the filter. |
| checkActionText String |
The value used by the comparison action. |
Simple Machine Filter Object
| X | X |
|---|---|
| includeGroups String Array Array |
Machine group paths that are explicitly included. |
| excludeGroups String Array Array |
Machine group paths that are explicitly excluded. |
| includeMachineIDs String Array |
Machine IDs that are explicitly included. |
| excludeMachineIDs String Array |
Machine IDs that are explicitly excluded. |
Fetch Customer Filters
/technicians/filters/customer/get
/groups/filters/customer/get
Return the customer Filter Objects configured on a technician or group.
Response Data
| X | X |
|---|---|
| Filter Object Array | The configured customer filter rules. |
Set Customer Filters
/technicians/filters/customer/set
/groups/filters/customer/set
Replace the customer filters configured on a technician or group.
POST Data Attributes
| X | X |
|---|---|
| filters Filter Object Array |
The replacement filters. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetch Advanced Machine Filters
/technicians/filters/machine/advanced/get
/groups/filters/machine/advanced/get
Return the advanced machine Filter Objects configured on a technician or group.
Response Data
| X | X |
|---|---|
| Filter Object Array | The configured advanced machine filter rules. |
Set Advanced Machine Filters
/technicians/filters/machine/advanced/set
/groups/filters/machine/advanced/set
Replace the advanced machine filters configured on a technician or group.
POST Data Attributes
| X | X |
|---|---|
| filters Filter Object Array |
The replacement filters. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetch Simple Machine Filters
/technicians/filters/machine/simple/list
/groups/filters/machine/simple/list
Return the simple machine filter configured on a technician or group.
Response Data
| X | X |
|---|---|
| Simple Machine Filter Object | The configured simple machine filters. |
Edit Simple Machine Filters
/technicians/filters/machine/simple/include
/technicians/filters/machine/simple/exclude
/technicians/filters/machine/simple/remove
/groups/filters/machine/simple/include
/groups/filters/machine/simple/exclude
/groups/filters/machine/simple/remove
Include, exclude, or remove machine IDs and machine group paths in the simple machine filter for a technician or group.
POST Data Attributes
| X | X |
|---|---|
| machineIDs String Array |
Machine IDs to include, exclude, or remove from the simple filter. |
| groups String Array Array |
Machine group paths to include, exclude, or remove from the filter. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Machine Queries
Machine queries allow a client to query the Remote Access Service list, and to retrieve certain monitoring and hardware information stored in the server. Services are represented in the API using Machine Objects.
Machine Object
| X | X |
|---|---|
| machineID String |
A unique identifier for a machine. |
| online Boolean |
true if the machine is currently online. |
| groups String Array |
An array of group names representing the group that this machine is in. |
| name String |
The name of this machine. |
| state String |
One of In Use, Not In Use, Headless or Unknown. |
| protocol String |
The current polling protocol. |
| lastRegistrationTime Long |
The timestamp of the last time this machine registered with the server, in milliseconds. |
| sessionCount Integer |
The number of active sessions. |
| monitoringEnabled Boolean |
true if this machine is currently monitoring. |
| hasLoggedInUser Boolean |
true if a user is currently logged in on the machine. |
| consoleUser String |
The current console user. |
| os String |
The remote machine operating system. |
| hostname String |
The remote machine hostname. |
| domain String |
The machine domain, if available. |
| workgroup String |
The machine workgroup, if available. |
| wanIP String |
The remote machine WAN IP address. |
| build String |
The SimpleHelp build running on the machine. |
| ipAddresses Network Adapter Object Array |
An array of Network Adapter Objects describing the local LAN adapters. |
| uptimeMS Long |
The machine uptime, in milliseconds. |
| properties Machine Property Object Array |
Machine properties, including inherited properties. |
Network Adapter Object
| X | X |
|---|---|
| ip String |
The LAN IP address for this adapter. |
| mac String |
The MAC address for this adapter. |
| name String |
The name of this adapter. |
Listing Machines
/machines/list
Return a list of all machines registering with the server
curl [SERVER]/machines/list \
-X POST \
-H "Content-Type: application/json"
Return a JSON array of Machine Objects detailing all Remote Access Services that are represented in the SimpleHelp server.
POST Data Attributes
| X | X |
|---|---|
| filter String |
A space-separated filter expression. Supported values are online, offline, used, unused, session, session=N, session>N, session<N, and upgrade. |
| sortBy String |
The Machine Object field to sort by. Prefix with - to sort descending. |
Response Data
| X | X |
|---|---|
| Machine Object Array | A JSON array of Machine Objects representing services that have registered with the server. |
Get Machine Details
/machines/get
Retrieve machine details by machine ID
curl [SERVER]/machines/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Fetch a Machine Object for a particular machine or set of machines. When exactly one machine is resolved, the response is a single Machine Object. When multiple machines are resolved, the response is an array of Machine Objects.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine for which details should be fetched. |
| machineIDs String Array |
The machine IDs of the machines for which details should be fetched. |
Response Data
| X | X |
|---|---|
| Machine Object or Machine Object Array | A Machine Object, or an array of Machine Objects, representing the requested machines. |
Change Machine Settings
/machines/set
Rename a machine
curl [SERVER]/machines/set \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234", name: "New Name"}'
Change settings for one or more remote machines.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine for which settings should be changed. |
| machineIDs String Array |
The machine IDs of the machines for which settings should be changed. |
| monitor Boolean |
Enable or disable monitoring for the specified machines (v5.2.12 or later). |
| autorestart Boolean |
Enable or disable automatic restart after updates for the specified machines. |
| name String |
Rename the specified machines. |
| groups String Array |
Move the specified machines to this machine group path. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Get Machine Hardware Details
/machines/hardware/get
Retrieve the hardware information for a machine
curl [SERVER]/machines/hardware/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Returns an array of Hardware Objects containing hardware details about the requested machines. Hardware details are detailed across multiple objects, each of which is outlined below.
Hardware Object
| X | X |
|---|---|
| machineID String |
The machine ID of the machine that this hardware is collected from. |
| totalMemory Long |
The total memory, in bytes. |
| modelName String |
The model name of this machine. |
| modelIdentifier String |
This model identifier of this machine. |
| manufacturer String |
The manufacturer of this machine. |
| serial String |
The serial number of this machine. |
| eccMemory Boolean |
true if this machine is using ECC memory. |
| memory Memory Object Array |
An array of Memory Objects detailing the installed memory. |
| disks Disk Object Array |
An array of Disk Objects detailing the disks in this machine. |
| processors Process Object Array |
An array of Processor Objects detailing the processors in this machine. |
| gpus GPU Object Array |
An array of GPU Objects detailing the graphics processors in this machine. |
Memory Object
| X | X |
|---|---|
| capacity Long |
The memory capacity in bytes. |
| type String |
The type of memory, such as DDR3. |
| speedHz Long |
The speed of the memory, in Hz. |
| status String |
The system produced status of this memory. |
| manufacturer String |
The manufacturer of this memory. |
Disk Object
| X | X |
|---|---|
| disk String |
The disk identifier used by the operating system. |
| deviceName String |
The name of this disk. |
| mediaName String |
The name of the disk media. |
| capacity Long |
The capacity of the disk, in bytes. |
| type String |
The type of disk, such as SSD. |
| protocol String |
The protocol of the disk. |
| internal Boolean |
true if this is an internal disk. |
Processor Config
| X | X |
|---|---|
| name String |
The name of this processor. |
| speedHz Long |
The speed of this processor in Hz. |
| cores Integer |
The number of cores. |
| is64bit Boolean |
true if this is a 64bit processor. |
GPU Object
| X | X |
|---|---|
| name String |
The name of this GPU. |
| vendor String |
The GPU vendor. |
| vramBytes Long |
The amount of VRAM, in bytes. |
| driverVersion String |
The GPU driver version. |
| deviceID String |
The GPU device identifier. |
| enabled Boolean |
true if this GPU is enabled. |
| coreCount Integer |
The number of GPU cores. |
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the remote access machine to be queried. |
| machineIDs String Array |
A string array of machine IDs of the Remote Access Services to be queried. |
Response Data
| X | X |
|---|---|
| Hardware Object Array | An array of Hardware Objects containing hardware details for the provided machine IDs. |
Get Machine Monitoring Details
/machines/monitoring/get
Fetch the latest monitoring information for a machine
curl [SERVER]/machines/monitoring/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Returns an array of Machine Monitoring Objects containing monitoring data retrieved from the specified machines.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the service to be queried. |
| machineIDs String Array |
A string array of machine IDs of the services to be queried. |
Response Data
| X | X |
|---|---|
| Machine Monitoring Object Array | An array of Monitoring Objects containing monitoring details for the provided machine IDs. |
Machine Monitoring Object
| X | X |
|---|---|
| machineID String |
The machine ID of the machine that this monitoring data is collected from. |
| cpuLoadAverages Integer Array |
The last collected CPU load averages. |
| memoryLoadAverages Integer Array |
The last collected memory load averages. |
| latestCpuPc Integer |
The latest CPU usage percentage. |
| latestMemoryPc Integer |
The latest memory usage percentage. |
| wifiMbit Double |
The latest Wi-Fi link speed, in Mbit/s. |
| wifiSignalPc Double |
The latest Wi-Fi signal percentage. |
| is64bit Boolean |
true if this is a 64bit machine. |
| os String |
The operating system name and version. |
| osEdition String |
The operating system edition, if available. |
| hostname String |
The hostname of this machine. |
| domain String |
The domain of this machine, if available. |
| workgroup String |
The workgroup of this machine, if available. |
| tenantID String |
The directory tenant ID, if available. |
| deviceID String |
The directory device ID, if available. |
| wanIP String |
The public WAN IP of this machine. |
| currentUser String |
The current console user. |
| lastRestarted Long |
The timestamp in milliseconds when this service was last restarted. |
| disks Disk Monitoring Array |
An array of Disk Monitoring objects. |
| cpuOffenders CPU Offender Array |
An array of CPU Offender Objects detailing processes using the most CPU. |
| networkAdapters Network Adapter Object Array |
An array of Network Adapter objects detailing the network interfaces on this machine. |
Disk Monitoring Object
| X | X |
|---|---|
| name String |
The name of the disk. |
| usedPercentage Double |
The percentage of disk space used. |
CPU Offenders Object
| X | X |
|---|---|
| name String |
The name of the offending process. |
| usedPercentage Double |
The percentage of CPU used. |
Fetch Machine Thumbnails
/machines/thumb/get
Fetch the latest thumbnail image for a machine
curl [SERVER]/machines/thumb/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Request and return thumbnail images for one or more machines. Each array entry is a data URL string for the corresponding machine, or an empty string if no image is available yet.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the service to be queried. |
| machineIDs String Array |
A string array of machine IDs of the services to be queried. |
Response Data
| X | X |
|---|---|
| String Array | An array of image data URL strings. |
Fetch Machine Screens
/machines/screen/get
Fetch the latest larger screen image for a machine
curl [SERVER]/machines/screen/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Request and return larger screen images for one or more machines. Each array entry is a data URL string for the corresponding machine, or an empty string if no image is available yet.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the service to be queried. |
| machineIDs String Array |
A string array of machine IDs of the services to be queried. |
Response Data
| X | X |
|---|---|
| String Array | An array of image data URL strings. |
Fetch Machine Notes
/machines/notes/get
Fetch the notes associated with a machine
curl [SERVER]/machines/notes/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Fetch the notes and warning text associated with one or more machines. When machineID is used, the response is a single Notes Response Object. When machineIDs is used, the response is an array of Notes Response Objects.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine for which notes should be fetched. |
| machineIDs String Array |
The machine IDs of the machines for which notes should be fetched. |
Response Data
| X | X |
|---|---|
| Notes Response Object or Notes Response Array | The notes for the requested machine or machines. |
Notes Response Object
| X | X |
|---|---|
| machineID String |
The machine ID of a machine. |
| notes String |
The notes associated with this machine. |
| warnings String |
The warning text associated with this machine. |
Setting Machine Notes
/machines/notes/set
Set the notes and warning text for a machine
curl [SERVER]/machines/notes/set \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234", notes: "Some notes", warning: "A warning"}'
Set the notes and warning text associated with a machine.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine for which notes should be set. |
| machineIDs String Array |
The machine IDs of the machines for which notes should be set. |
| notes String |
The notes to be associated with this machine. |
| warnings String |
The warning text to be associated with this machine. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetching Machine Properties
/machines/properties/get
Fetch the machine properties associated with a machine
curl [SERVER]/machines/properties/get \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234"}'
Fetch the properties associated with one or more machines. When a key is specified and exactly one machine is resolved, the response is the property value string. When no key is specified and exactly one machine is resolved, the response is a Machine Properties Object. Requests that resolve multiple machines return an array of Machine Properties Objects.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine to query. |
| machineIDs String Array |
The machine IDs of the machines to query. |
| includeInherited Boolean |
Set to true to include properties inherited from ancestor machine groups. |
| key String |
If specified, the key of the property to fetch. If absent, all properties will be returned. |
Response Data
| X | X |
|---|---|
| String | If key and a single machineID are specified, the value associated with the requested key. |
| Machine Properties Object | If a single machineID is specified without key, the properties for that machine. |
| Machine Properties Object Array | If machineIDs is specified, an array of Machine Properties Objects, one for each machine requested. |
Machine Properties Object
| X | X |
|---|---|
| machineID String |
The machine ID of the machine to query. |
| properties Machine Property Object Array |
An array of Machine Property Objects. |
Machine Property Object
| X | X |
|---|---|
| key String |
The key of the machine property. |
| value String |
The value of the machine property. |
Setting Machine Properties
/machines/properties/set
Set a property "License":"License Value" for a machine
curl [SERVER]/machines/properties/set \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234", key: "License", value: "License Value"}'
Set a key=value property for one or more machines.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine to query. |
| machineIDs String Array |
The machine IDs of the machines to query. |
| key String |
The key of the machine property. |
| value String |
The value of the machine property. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Removing Machine Properties
/machines/properties/remove
Remove a property "License" for a machine
curl [SERVER]/machines/properties/remove \
-X POST \
-H "Content-Type: application/json"
-d '{machineID: "SG_1234", key: "License"}'
Remove Machine Properties from one or more machines.
POST Data Attributes
| X | X |
|---|---|
| machineID String |
The machine ID of the machine to remove a property from. |
| machineIDs String Array |
The machine IDs of the machines to remove a property from. |
| key String |
The key of the machine property to remove. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetching Machine Group Properties
/machinegroups/properties/get
Fetch the machine group properties for the group 'London' with parent group 'United Kingdom'.
curl [SERVER]/machinegroups/properties/get \
-X POST \
-H "Content-Type: application/json"
-d '{groups: ["United Kingdom", "London"], includeInherited: true}'
Fetch the group properties associated with a machine group, and optionally return properties inherited from ancestor groups.
POST Data Attributes
| X | X |
|---|---|
| groups String Array |
An array of group names identifying a path in the group hierarchy. |
| includeInherited Boolean |
Set to true to include properties inherited from ancestor machine groups. |
| key String |
If specified, the key of the property to fetch. If absent, all keys are returned. |
Response Data
| X | X |
|---|---|
| String Array | If no key is specified, a string array containing all the keys for this group's properties. |
| String | If a key is specified, the value associated with this key. |
Setting Machine Group Properties
/machinegroups/properties/set
Set the machine group property 'exampleKey'='exampleValue' for the group 'London' with parent group 'United Kingdom'.
curl [SERVER]/machinegroups/properties/set \
-X POST \
-H "Content-Type: application/json"
-d '{groups: ["United Kingdom", "London"], key: "exampleKey", value: "exampleValue"}'
Set a key value pair associated with a machine group.
POST Data Attributes
| X | X |
|---|---|
| groups String Array |
An array of group names identifying a path in the group hierarchy. |
| key String |
The key of the machine group property to set. |
| value String |
The value of the machine group property to set. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Removing Machine Group Properties
/machinegroups/properties/remove
Remove the machine group property 'exampleKey' from the group 'London' with parent group 'United Kingdom'.
curl [SERVER]/machinegroups/properties/remove \
-X POST \
-H "Content-Type: application/json"
-d '{groups: ["United Kingdom", "London"], key: "exampleKey"}'
Remove a property associated with a machine group.
POST Data Attributes
| X | X |
|---|---|
| groups String Array |
An array of group names identifying a path in the group hierarchy. |
| key String |
The key of the machine group property to remove. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Server Queries
Server Queries are general purpose requests that allow you to manage technician restrictions and request a configuration backup.
Retrieve Technician Restrictions
/server/tech-restrictions/get
Retrieve technician IP restrictions
curl [SERVER]/server/tech-restrictions/get \
-X POST \
-H "Content-Type: application/json"
Retrieve the current set of IP restrictions, each expressed as a regular expression.
Response Data
| X | X |
|---|---|
| String Array | A String Array with each string representing a single technician restriction, which restricts the source network that technicians are able to log in from. |
Adding New Technician Restrictions
/server/tech-restrictions/new
Add IP 1.2.3.4 as an IP restriction
curl [SERVER]/server/tech-restrictions/new \
-X POST \
-H "Content-Type: application/json"
-d "{restrictions: ['1.2.3.4']}"
Add IP restrictions to the current set of restrictions, with each expressed as a regular expression.
POST Data Attributes
| X | X |
|---|---|
| restrictions String Array |
A String Array with each string representing a single technician restriction that will be added. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Setting Technician Restrictions
/server/tech-restrictions/set
Replace technician IP restrictions
curl [SERVER]/server/tech-restrictions/set \
-X POST \
-H "Content-Type: application/json"
-d "{restrictions: ['1.2.3.4']}"
Replace the current set of IP restrictions, with each expressed as a regular expression.
POST Data Attributes
| X | X |
|---|---|
| restrictions String Array |
A String Array with each string representing a single technician restriction that will be applied. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Removing Technician Restrictions
/server/tech-restrictions/remove
Remove IP 1.2.3.4 as an IP restriction
curl [SERVER]/server/tech-restrictions/remove \
-X POST \
-H "Content-Type: application/json"
-d "{restrictions: ['1.2.3.4']}"
Remove IP restrictions from the current set of restrictions, with each expressed as a regular expression.
POST Data Attributes
| X | X |
|---|---|
| restrictions String Array |
A String Array with each string representing a single technician restriction that will be removed. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Request a Configuration Backup
/server/backup-config
A request that will cause the SimpleHelp server to save a timestamped backup of the configuration file to configuration/backups/api in the SimpleHelp server installation directory.
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
Fetch the Server Hostname
/server/hostname/get
Retrieve the hostname
curl [SERVER]/server/hostname/get \
-X POST \
-H "Content-Type: application/json"
Retrieve the hostname for this SimpleHelp server, as configured in the Network Settings section of the Administration tab.
Response Data
| X | X |
|---|---|
| String | The currently configured hostname. |
Set the Server Hostname
/server/hostname/set
Set the hostname for this server to 'simplehelp.server.com'
curl [SERVER]/server/hostname/set \
-X POST \
-H "Content-Type: application/json"
-d "{hostname: 'simplehelp.server.com'}"
Set the server's hostname, as configured in the Network Settings section of the Administration tab.
POST Data Attributes
| X | X |
|---|---|
| hostname String |
The hostname to configure. |
Response Data
| X | X |
|---|---|
| API Response Object | A response indicating success or failure. |
History Queries
Query the server’s history repository to retrieve details of previous sessions. History results are serialised in a JSON History Object.
History Object
| X | X |
|---|---|
| sessionID String |
The unique session ID of this session. |
| type String |
The type of session. One of Access, Support or Presentation. |
| technicianName String |
The display name of the technician who started the session. |
| technicianUsername String |
The username of the technician who started the session. |
| start Long |
The start time of this session, in milliseconds. |
| duration Long |
The duration of this session, in milliseconds. |
| lastModified Long |
The time that this session was last updated, in milliseconds. |
| hasRecording Boolean |
true if this session has a synchronised recording. |
| chat String |
A copy of the chat transcript. |
| comments String |
A copy of the technician comments. |
| sessionEvents String Array |
Session event log entries. |
| mode String |
The initial session mode. One of “Mobile”, “File Transfer”, “Diagnostics”, “App Tunnel”, “VNC” or “Terminal”. |
| appTunnelTarget String |
The app tunnel configuration (if this is an App Tunnel session). |
| machine Machine Object |
A description of the remote machine connected to (for access sessions). |
| customer Customer Object |
A description of the customer connected to (for support sessions). |
Customer Object
| X | X |
|---|---|
| customerID String |
The unique customer ID for this customer. |
| timeInQueue Long |
The time the customer spent waiting in the queue, in milliseconds. |
| username String |
The customer’s local operating system username. |
| country String |
The customer’s detected country. |
| domain String |
The domain that the customer used to access the SimpleHelp server. |
| url String |
The URL that the customer used to access the SimpleHelp server. |
| os String |
The customer’s operating system. |
| hostname String |
The customer’s local machine hostname. |
| wanIP String |
The detected WAN IP address from where the customer connected. |
| ipAddresses String Array |
The local LAN IP addresses configured on the customer’s machine. |
| details Map (String > String) |
The customer details entered when first initiating a session. Keys are the labels specified, and values are the customer entered details. |
Listing Historical Sessions
/history/list
Retrieve the last 100 sessions in the history
curl [SERVER]/history/list \
-X POST \
-H "Content-Type: application/json"
-d "{maxResults: 100}"
Retrieve details of historical sessions.
POST Data Attributes
| X | X |
|---|---|
| rangeStart Long |
Return sessions that started at, or after, the specified time in milliseconds. |
| rangeEnd Long |
Return sessions that started before the specified time in milliseconds. |
| rangeLastModified Boolean |
Set to true to return sessions where rangeStart and rangeEnd restrict the last modified time of the session rather than the start time. |
| maxResults Integer |
The maximum results to return. The default is 50. |
| textFilter String |
Include sessions that match the specified text filter. |
| technicianNameFilters String Array |
Include sessions where the technician names match one or more of the specified filters. |
| groupFilters Integer Array |
Include sessions where the technicians are in groups with the specified group IDs. |
| machineIDFilters String Array |
Include sessions to machines with the specified machine IDs. |
| includeSupportSessions Boolean |
Set to true to include remote support sessions. The default is true. |
| includeAccessSessions Boolean |
Set to true to include remote access sessions. The default is true. |
| includePresentationSessions Boolean |
Set to true to include presentation sessions. The default is true. |
| includeRemoteWorkSessions Boolean |
Set to true to include remote work sessions. The default is true. |
| includeToolSessions Boolean |
Set to true to include toolbox run sessions. The default is true. |
| includeAISessions Boolean |
Set to true to include AI sessions. The default is true. |
| includeChat Boolean |
Set to true to include chat transcripts. The default is false. |
| includeEvents Boolean |
Set to true to include session event log entries. The default is false. |
| searchUntilSessionID String |
Return results until the specified session ID is encountered. |
| sessionID String |
Return the session with the specified session ID. |
| sortBy String |
The History Object field to sort by. Prefix with - to sort descending. |
Response Data
| X | X |
|---|---|
| History Object Array | The list of history objects returned by the query. |
Alerts Queries
Retrieves monitoring alerts configured on the server and their triggered status data (including inactive Alerts). This does not include server events.
Machine Name Object
| X | X |
|---|---|
| name String |
The machine or alert name. |
| group String Array |
The machine group path. |
Alert Object
| X | X |
|---|---|
| name Machine Name Object |
The alert name and group path. |
| active Boolean |
true if the alert is currently enabled, false otherwise. |
| triggered Boolean |
true if the alert is currently triggered, false otherwise. |
| triggeredMachineIDs String Array |
An array of machine IDs of triggered machines. |
| reason String |
A more complete reason about why the alert triggered. |
| shortReason String |
A short reason about why the alert triggered. |
| lastReportMS Long |
The timestamp that this alert last reported its state. |
| stateAgeMS Long |
The duration, in milliseconds, that this alert has been in the current state. |
| severity String |
One of information, severe, critical and warning. |
Listing Alerts
/alerts/list
Retrieve the alerts
curl [SERVER]/alerts/list \
-X POST \
-H "Content-Type: application/json"
Retrieve details of monitoring alerts.
Response Data
| X | X |
|---|---|
| Alert Object Array | The list of alert objects returned by the query. |
Session Queries
Retrieve the list of active support or access sessions, or query the waiting session queue.
Support Session Queries
Query the server for customer initiated support sessions that are in the waiting queue, or currently in session.
Support Session Object
| X | X |
|---|---|
| customer Customer Object |
The customer details for this support session. |
| technicianDisplayName String |
The technician's name. |
| technicianUsername String |
The technician's username. |
| technicianID Integer |
The technician's unique account ID. |
| sessionID String |
The unique session ID for this session. |
| elapsedTime Long |
The session duration, in milliseconds. |
| startTime Long |
The start time of the session, in milliseconds. |
Listing Queued Customers
/support/queue/list
Retrieve the list of customers in the waiting queue
curl [SERVER]/support/queue/list \
-X POST \
-H "Content-Type: application/json"
Retrieve the list of customers waiting in the support queue.
Response Data
| X | X |
|---|---|
| Customer Object Array | An array of Customer Objects. |
Listing Active Support Sessions
/support/sessions/list
Retrieve the list of active support sessions
curl [SERVER]/support/sessions/list \
-X POST \
-H "Content-Type: application/json"
Response Data
| X | X |
|---|---|
| Support Session Object Array | An array of Support Session objects. |
Access Session Queries
Query the server for access sessions that are currently in session.
Access Session Object
| X | X |
|---|---|
| machine Machine Object |
The machine details for this access session. |
| technicianDisplayName String |
The technician's name. |
| technicianUsername String |
The technician's username. |
| technicianID Integer |
The technician's unique account ID. |
| sessionID String |
The unique session ID for this session. |
| elapsedTime Long |
The session duration, in milliseconds. |
| startTime Long |
The start time of the session, in milliseconds. |
Listing Active Access Sessions
/access/sessions/list
Retrieve the list of active access sessions
curl [SERVER]/access/sessions/list \
-X POST \
-H "Content-Type: application/json"
Retrieve the list of active access sessions. These are sessions initiated to Remote Access Services in the Access tab.
Response Data
| X | X |
|---|---|
| Access Session Object Array | An array of Access Session objects. |
Tools Queries
Tools queries list the tools (scripts and commands) visible to a technician, launch them on one or more machines, and retrieve the status and output of those runs.
Tools are launched as a named technician. The set of tools available, and the permissions applied when the tool runs, come from that technician's own toolbox and the shared toolbox groups they have been granted access to. Every tool query must identify the technician using either uniqueID or username.
ToolBox Item Object
| X | X |
|---|---|
| toolID String |
The unique identifier of the tool. |
| name String |
The tool's display name. |
| type String |
The tool type. One of script or command. |
| notes String |
Any notes configured on the tool. |
| targetOperatingSystem String |
The operating system this tool targets, or null if the tool is not restricted to a specific OS. |
Listing Tools
/tools/list
Retrieve the tools visible to a technician
curl [SERVER]/tools/list \
-X POST \
-H "Content-Type: application/json" \
-d '{username: "testuser"}'
Retrieve the list of tools that are visible to the specified technician. The list contains tools from the technician's own toolbox as well as tools from any shared toolbox groups that have been imported by the technician and that the technician is allowed to use.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
The unique identifier of the technician whose tools should be returned. |
| username String |
The username of the technician whose tools should be returned. Used if uniqueID is not given. |
Response Data
| X | X |
|---|---|
| ToolBox Item Object Array | An array of ToolBox Item Objects visible to the technician. |
Running a Tool
/tools/run
Run a tool against one or more machines
curl [SERVER]/tools/run \
-X POST \
-H "Content-Type: application/json" \
-d '{username: "test-user", toolID: "tool-id-1", machineIDs: ["SG_111","SG_222"]}'
Launch a tool against one or more machines as the specified technician. The tool must either be in the technician's own toolbox or in a shared toolbox group that the technician has access to. The call returns immediately with a runID that can be used to poll for the status and output of the run using /tools/run/status and /tools/run/output.
Run results are retained for 60 minutes after they were last accessed, after which they expire and can no longer be queried.
POST Data Attributes
| X | X |
|---|---|
| uniqueID Integer |
The unique identifier of the technician to run the tool as. |
| username String |
The username of the technician to run the tool as. Used if uniqueID is not given. |
| toolID String |
The unique identifier of the tool to run. |
| toolName String |
The name of the tool to run. Used if toolID is not given. |
| machineIDs String Array |
An array of machine IDs to run the tool against. |
| machineID String |
A single machine ID to run the tool against. Used if machineIDs is not given. |
Response Data
| X | X |
|---|---|
| runID String |
A unique identifier for the tool run, used to poll for status and output. |
Fetching Tool Run Status
/tools/run/status
Retrieve the status of a tool run
curl [SERVER]/tools/run/status \
-X POST \
-H "Content-Type: application/json" \
-d '{runID: "1700000000001"}'
Retrieve the current status of a tool run previously started via /tools/run. The response includes an entry for each target machine with its return code (once the tool has completed on that machine).
Tool Run Machine Status Object
| X | X |
|---|---|
| machineID String |
The machine ID that the tool was run against. |
| machineName String |
The machine's display name. |
| returnCode Integer |
The return code reported by the tool, or null if the tool has not yet completed on this machine. |
| complete Boolean |
true once a return code has been reported for this machine. |
Tool Run Status Object
| X | X |
|---|---|
| runID String |
The run identifier. |
| toolID String |
The identifier of the tool that was launched. |
| toolName String |
The name of the tool that was launched. |
| startTime Long |
The time the run was started, in milliseconds. |
| elapsedTimeMs Long |
The elapsed time since the run was started, in milliseconds. |
| complete Boolean |
true when all target machines have reported a return code. |
| machines Tool Run Machine Status Array |
The per-machine status entries for this run. |
POST Data Attributes
| X | X |
|---|---|
| runID String |
The run identifier returned by /tools/run. |
Response Data
| X | X |
|---|---|
| Tool Run Status Object | The current status of the tool run. |
Fetching Tool Run Output
/tools/run/output
Retrieve the captured output from a tool run
curl [SERVER]/tools/run/output \
-X POST \
-H "Content-Type: application/json" \
-d '{runID: "1700000000001"}'
Retrieve the output captured from each machine for a tool run previously started via /tools/run. Machines that have not yet reported a result are omitted from the machines array; poll /tools/run/status to determine when each machine is complete.
Tool Run Machine Output Object
| X | X |
|---|---|
| machineID String |
The machine ID that the tool was run against. |
| returnCode Integer |
The return code reported by the tool on this machine. |
| stdout String |
The standard output captured from the tool. |
| stderr String |
The standard error captured from the tool. |
| preLaunchError String |
A message describing any failure that prevented the tool from launching on this machine, if any. |
Tool Run Output Object
| X | X |
|---|---|
| runID String |
The run identifier. |
| machines Tool Run Machine Output Array |
An array of per-machine output entries, one for each machine that has reported. |
POST Data Attributes
| X | X |
|---|---|
| runID String |
The run identifier returned by /tools/run. |
Response Data
| X | X |
|---|---|
| Tool Run Output Object | The captured output from the tool run, per machine. |