Page History

...

Field	Type	Description
description	String	Description of this Element.
groupId	Integer	ID for this Element's parent Element group.
hostname	String	Hostname used to contact this Element.
id	Integer	ID for this Element.
isMonitored	Boolean	Monitoring status for this Element.
monitors	Array	An array listing all monitors that belong to this Element (see Monitors Array below for details).
name	String	The display name of this Element.
tags	Array	An array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildren	Array	An array listing all Elements that are a topological dependency of this Element in up.time Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParents	Array	An array listing all Elements that are topological parents of this Element in up.time Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeName	String	A basic type definition for the Element. The following types are supported: server network device Application
typeOs	String	Returns basic operating system information for this Element: server: operating system network device: `sysDescr` value Application: no result is returned Elements of other types are not currently supported by the API.
typeSubtype	String	Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported: server AIX Linux Netware Solaris Windows Hpux EsxServer IbmPowerSystems VcenterServer VcenterHostSystem Unknown network device switch Application Application
typeSubtypeName	String	Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes.

...

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time Uptime Infrastructure Monitor uses, and can be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

...

Field	Type	Description
description	String	Description of this Element.
groupId	Integer	ID for this Element's parent Element group.
hostname	String	Hostname used to contact this Element.
id	Integer	ID for this Element.
isMonitored	Boolean	Monitoring status for this Element.
monitors	Array	An array listing all monitors that belong to this Element (see Monitors Array below for details).
name	String	The display name of this Element.
tags	Array	An array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildren	Array	An array listing all Elements that are a topological dependency of this Element in up.time Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParents	Array	An array listing all Elements that are topological parents of this Element in up.time Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeName	String	A basic type definition for the Element. The following types are supported: server network device Application
typeOs	String	Returns basic operating system information for this Element: server: operating system network device: `sysDescr` value Application: no result is returned Elements of other types are not currently supported by the API.
typeSubtype	String	Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported: server AIX Linux Netware Solaris Windows Hpux EsxServer IbmPowerSystems VcenterServer VcenterHostSystem Unknown network device switch Application Application
typeSubtypeName	String	Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes.

...

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time Uptime Infrastructure Monitor uses, and can be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

...

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1000	Element Does Not Exist	404	A specifically referenced Element ID does not exist. In such a case, referencing `https://youruptime:9997/api/v1/elements/12345` would return the following: `The element id '12345' does not exist.` The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in upUptime Infrastructure Monitor.time.
UT-1010	Element Filter Expired	410	The filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1012	Element Group Filter Expired	410	The group filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1013	Invalid Element Filter	400	The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1015	Invalid Element Group Filter	400	The JSON used to create an Element group filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1028	URL ID Body Mismatch	400	The Element ID in the URL and the JSON object do not match.

...

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time Uptime Infrastructure Monitor uses, and can be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor
message	String	the output message produced the last time the service monitor was executed
status	String	the last known status of this service monitor
lastCheckTime	String - Date Time	the last time this service monitor was executed successfully
lastTransitionTime	String - Date Time	the last time this service monitor changed status; this field can be used to determine time in the current status

...

Response Code	Code Description	HTTP Status Code	Details
	OK	200	Information retrieved successfully.
UT-1000	Element Does Not Exist	404	A specifically referenced Element ID does not exist. In such a case, referencing `https://youruptime:9997/api/v1/elements/12345` would return the following: `The element id '12345' does not exist.` The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in up.timeUptime Infrastructure Monitor.
UT-1010	Element Filter Expired	410	The filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1012	Element Group Filter Expired	410	The group filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1013	Invalid Element Filter	400	The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1015	Invalid Element Group Filter	400	The JSON used to create an Element group filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1028	URL ID Body Mismatch	400	The Element ID in the URL and the JSON object do not match.

...

Property	Description	Requirements
id	the id of the Element you want to update	required property must match an Element ID
name	display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface	must be unique maximum 50 characters
description	description for the Element	maximum 255 characters
hostname	resolvable network hostname or IP address of the Element	must be unique maximum 255 characters contains no whitespace characters
groupId	the Element Group to which the Element belongs	must match valid `groupId` end-user's user group is able to see the Element group
isMonitored	enables and disables monitoring for the Element, determining whether it appears in Global Scan and other dashboards	must be Boolean

Notes

In up.timeUptime Infrastructure Monitor, vCenter-based Elements (specifically, VMs and ESX hosts) are typically managed via vSync. This synchronization includes an Element's display name and hostname. Modifying either property through the API automatically disables its synchronization. Re-enabling the property must be done manually through the up.time Uptime Infrastructure Monitor Web interface (using the Element's Sync Display Name and Sync Hostname option).

...

Response Code	Code Description	HTTP Status Code	Details
UT-0200	OK	200	Operation performed successfully.
UT-1000	Element Does Not Exist	404	A specifically referenced Element ID does not exist. In such a case, referencing `https://youruptime:9997/api/v1/elements/12345` would return the following: `The element id '12345' does not exist.` The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in upUptime Infrastructure Monitor.time.
UT-1002	Element Group Does Not Exist	400	The referenced group ID does not exist.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1028	URL ID Body Mismatch	400	The Element ID in the URL and the JSON object do not match.
UT-1029	Duplicate Hostname	200	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	200	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Setting this Element to `isMonitored` exceeds the current license.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1041	Proxy Error	400	This error can occur when your deployment includes a UI instance.
UT-1042	HMC Violation	400	This error can occur when updating a pSeries-based Element that uses the HMC.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, or hostname is missing.
UT-1044	Field Number out of Range	n/a (JSON validation)	The declared Element group ID needs to be equal to or greater than 1.
UT-1045	Field Too Long	n/a (JSON validation)	One or more of the Element's name, description, or hostname exceed the maximum number of characters.

...

Property	Description	Requirements
name	display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface	required property must be unique maximum 50 characters
description	optional description for the Element	maximum 255 characters
hostname	resolvable network hostname or IP address of the Element	required property must be unique maximum 255 characters contains no whitespace characters
groupId	the Element Group the Element is placed in upon creation	required property must match valid `groupId` end-user's user group is able to see the Element group
type	the basic Element type: Server Network Device	required property must match one of the basic Element types (in this case, `Server`)
collectionMethod	array of data-collection properties describing how up.time Uptime Infrastructure Monitor communicates with the Element	required property
connectionType	the connection method for the Element: agent wmi snmp	required property must match one of the Element connection methods (in this case, `agent`)
useGlobalConnectionSettings	Boolean determining whether the up.time Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Element Settings if `true`, all other connection properties are ignored	defaults to `false` if property is not defined
port	the port through which the up.time Uptime Infrastructure Monitor Agent communicates with the Monitoring Station	required if useGlobalConnectionSettings property is `false` must be a valid port number (default 9998)
useSSL	Boolean indicating whether the up.time Uptime Infrastructure Monitor Agent securely communicates with the Monitoring Station using SSL	required if useGlobalConnectionSettings property is `false` must be Boolean

...

Example

Add a server that has an up.time Uptime Infrastructure Monitor Agent installed for data collection:

...

Field Description Requirements

name

display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface

required property
must be unique
maximum 50 characters

description

optional description for the Element

maximum 255 characters

hostname

resolvable network hostname or IP address of the Element

required property
must be unique
maximum 255 characters
contains no whitespace characters

groupId

the Element Group the Element is placed in upon creation

required property
must match valid groupId
end-user's user group is able to see the Element group

type

the basic Element type:

Server
Network Device

required property
must match one of the basic Element types (in this case, Server)

collectionMethod

array of data-collection properties describing how up.time Uptime Infrastructure Monitor communicates with the Element

required property

connectionType

the connection method for the Element:

agent
wmi
snmp

required property
must match one of the Element connection methods (in this case, wmi)

useGlobalConnectionSettings

Boolean determining whether the up.time Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Element Settings

if true, all other connection properties are ignored

defaults to false if property is not defined

wmiDomain

the Windows domain in which WMI is implemented

required if useGlobalConnectionSettings property is false

wmiUsername

the name of the account with access to WMI on the Windows domain

required if useGlobalConnectionSettings property is false

wmiPassword

the password for the username above

Info
the plain-text password is passed to up.time Uptime Infrastructure Monitor using an encrypted connection

required if useGlobalConnectionSettings property is false

...

Field	Description	Requirements
name	display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface	required property must be unique maximum 50 characters
description	optional description for the Element	maximum 255 characters
hostname	resolvable network hostname or IP address of the Element	required property must be unique maximum 255 characters contains no whitespace characters
groupId	the Element Group the Element is placed in upon creation	required property must match valid `groupId` end-user's user group is able to see the Element group
type	the basic Element type: Server Network Device	required property must match one of the basic Element types (in this case, `Server`)
collectionMethod	array of data-collection properties describing how up.time Uptime Infrastructure Monitor communicates with the Element	required property
connectionType	the connection method for the Element: agent wmi snmp	required property must match one of the Element connection methods (in this case, `snmp`)
useGlobalConnectionSettings	Boolean determining whether Global SNMP Configuration Settings are set in Global Element Settings if `true`, all other connection properties are ignored	defaults to `false` if property is not defined
snmpVersion	the SNMP version used to connect to the network device: v2 v3	required if `useGlobalConnectionSettings` is `false` must match one of the valid SNMP versions (in this case, `v2`)
snmpPort	the port on which the device is listening	required if `useGlobalConnectionSettings` is `false` must be a valid port number (default `161`)
snmpV2ReadCommunity	the SNMP community to use for the connection, typically set to `public`	required if `useGlobalConnectionSettings` is `false`
isPingable	determines whether up.time Uptime Infrastructure Monitor can contact the device using the ping utility	required if `useGlobalConnectionSettings` is `false` must be Boolean

...

Field Description Requirements

name

display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface

required property
must be unique
maximum 50 characters

description

optional description for the Element

maximum 255 characters

hostname

resolvable network hostname or IP address of the Element

required property
must be unique
maximum 255 characters
contains no whitespace characters

groupId

the Element Group the Element is placed in upon creation

required property
must match valid groupId
end-user's user group is able to see the Element group

type

the basic Element type:

Server
Network Device

required property
must match one of the basic Element types (in this case, Server)

collectionMethod

array of data-collection properties describing how up.time Uptime Infrastructure Monitor communicates with the Element

required property

connectionType

the connection method for the Element:

agent
wmi
snmp

required property
must match one of the Element connection methods (in this case, snmp)

useGlobalConnectionSettings

Boolean determining whether Global SNMP Configuration Settings are set in Global Element Settings

if true, all other connection properties are ignored

defaults to false if property is not defined

snmpVersion

the SNMP version used to connect to the network device:

v2
v3

required property
must match one of the valid SNMP versions (in this case, v3)

snmpPort

the port on which the device is listening

required if useGlobalConnectionSettings is false
must be a valid port number (default 161)

snmpV3Username

the name required to connect to the network device

required if useGlobalConnectionSettings is false

snmpV3AuthenticationPassword

the password required to connect to the network device

Info
the plain-text password is passed to up.time Uptime Infrastructure Monitor using an encrypted connection

required if useGlobalConnectionSettings is false

snmpV3AuthenticationMethod

determines how encrypted data moving between the network device and up.time Uptime Infrastructure Monitor is authenticated:

MD5
SHA

required if useGlobalConnectionSettings is false
must match one of the valid authentication methods

snmpV3PrivacyPassword

the password used to encrypt data moving between the network device and up.timeUptime Infrastructure Monitor

Info
the plain-text password is passed to up.time Uptime Infrastructure Monitor using an encrypted connection

required if useGlobalConnectionSettings is false

snmpV3PrivacyType

determines how data moving between the network device and up.time Uptime Infrastructure Monitor is encrypted:

DES
AES

required if useGlobalConnectionSettings is false
must match one of the valid privacy types

isPingable

determines whether up.time Uptime Infrastructure Monitor can contact the device using the ping utility

required if useGlobalConnectionSettings is false
must be Boolean

...

vCenter-based Elements mirrored in up.time Uptime Infrastructure Monitor via vSync cannot be deleted, only ignored:

...

Response Code	Code Description	HTTP Status Code	Details
	No Content	204	Operation performed successfully.
UT-1000	Element Does Not Exist	404	A specifically referenced Element ID does not exist. In such a case, referencing `https://youruptime:9997/api/v1/elements/12345` would return the following: `The element id '12345' does not exist.` The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in up.timeUptime Infrastructure Monitor.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1026	VM Not Deleted	403	VMs and ESX hosts that are ignored cannot be deleted.
UT-1027	Element Not Deleted	403	You are trying to delete an ESX host that is part of a cluster.
UT-1032	Manual Monitor Not Deleted	403	Manually monitored hosts cannot be deleted.

...

DELETE https://youruptime/api/v1/elements/16

Page tree

Versions Compared

Old Version 7

New Version 8

Key

Notes

Example