NAV

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/api_token/query

where:

  • host - the hostname of your SimpleHelp server
  • port - the port to connect on
  • api_token - a server-specific API token that can be generated in the Administration tab of the Technician Console
  • 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 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.
isAnonymous
Boolean		 true if this is an account that has been created by the SimpleHelp server after an anonymous group-based login.
allowLocallyAuthenticatedLogins
Boolean		 true if this technician can login using their account password.
enabled
Boolean		 true if this technician’s account is currently enabled.
appProfilesUser
Boolean		 true if this is an account created specifically for preconfigured applications.
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.

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:"testuser@simple-help.com}}'

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 reconfigured 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 follow 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_userShSessions
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.
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 creating 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.
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.
passwordSettings
Password Settings Object		 A Password Settings Object describing whether group password authentication is permitted.

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.

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.

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/get \ 
  -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.

Setting a Group Password

/groups/password/set

Set the Technician Group password

curl [SERVER]/groups/password/set \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{uniqueID: 1234, password: "abcd1234"}'

Set the password for this technician group.

POST Data Attributes

X X
uniqueID
Integer		 If specified lookup a group by this uniqueID.
group
Technician Group Object		 If specified lookup a group using the name attribute of this Technician Group object.
password
String		 The new password to set.

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.
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 true for 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.
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.

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.
os
String		 The remote machine operating system.
hostname
String		 The remote machine hostname.
wanIP
String		 The remote machine WAN IP address.
ipAddresses
Network Adapter Object Array		 An array of Network Adapter Objects describing the local LAN adapters.

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.

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.

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 Array A JSON array of Machine Objects representing the details of 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 details should be fetched.
machineIDs
String Array		 The machine IDs of the machines for which details should be fetched.
monitor
Boolean		 Enable or disable monitoring for the specified machines (v5.2.12 or later).

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 Machine 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 his 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.

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
String		 The speed of this processor in Hz.
cores
Integer		 The number of cores.
is64bit
Boolean		 true if this is a 64bit processor.

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
Machine 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.
is64bit
Boolean		 true if this is a 64bit machine.
os
String		 The operating system name and version.
hostname
String		 The hostname of this machine.
wanIP
String		 The public WAN IP of this machine.
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 processors that are using the majoring of the 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 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.

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 Array An array of Notes Response objects.

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.
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.

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
Machine Properties Object Array 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.
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.
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 Kingdon", "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.

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/get \ 
  -X POST \
  -H "Content-Type: application/json"
  -d '{groups: ["United Kingdon", "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.

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.

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/get \ 
  -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.

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.
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 attached group ID photos.
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.
searchUntilSessionID
String		 Return results until the specified session ID is encountered.

Response Data

X X
History Object Array The list of history objects returned by the query.

Alerts Queries

Retrieve the monitoring alerts.

Alert Object

X X
name
String		 The alert name.
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 historical sessions.

Response Data

X X
Alert Object The list of alerts 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 a 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 Sessions

/support/queue/list

Retrieve the list of sessions in the waiting queue

curl [SERVER]/support/queue/list \ 
  -X POST \
  -H "Content-Type: application/json"

Retrieve the list of sessions in the waiting queue

Response Data

X X
Support Session Object Array An array of Support Session 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 a 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.