Skip to end of metadata
Go to start of metadata

Summary

List all Elements and attached service monitors; display an Element's information and attached service monitors; display an Element's information and its current status; determine the topological parent of an Element:

Update an Element configuration:

Add or delete an Element:

 


GET /api/v1/elements

List all Elements visible to the authenticated user account.

Returned Fields

For each returned Element the following fields are provided:

FieldTypeDescription
descriptionStringDescription of this Element.
groupIdIntegerID for this Element's parent Element group.
hostnameStringHostname used to contact this Element.
idIntegerID for this Element.
isMonitoredBooleanMonitoring status for this Element.
monitorsArrayAn array listing all monitors that belong to this Element (see Monitors Array below for details).
nameStringThe display name of this Element.
tagsArrayAn array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildrenArrayAn array listing all Elements that are a topological dependency of this Element in Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParentsArrayAn array listing all Elements that are topological parents of this Element in Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeNameString

A basic type definition for the Element. The following types are supported:

  • server
  • network device
  • Application
typeOsString

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.

typeSubtypeString

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
typeSubtypeNameString

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.

Monitors Array

The monitors array is the same across all end points. For each monitor associated with this Element the following fields are provided:

FieldTypeDescription
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor
Tags Array

For each tag or view associated with this Element, the following fields are provided:

FieldTypeDescription
idIntegerID of the tag or view
nameString

name of the tag or view

Topological Children Array

For each Element that is topologically dependent on this Element, the following fields are provided:

FieldTypeDescription
idIntegerID of the child Element
isMonitoredBooleanmonitoring status for the Element
nameStringname of the Element
Topological Parents Array

For each Element on which this Element is topologically dependent, the following fields are provided:

FieldTypeDescription
idIntegerID of the parent Element
isMonitoredBooleanmonitoring status for the Element
nameStringname of the Element

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1010Element Filter Expired410

The filter you are referencing is expired. Created filters persist, by default, for five minutes.

UT-1013Invalid Element Filter400The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1028URL ID Body Mismatch400The Element ID in the URL and the JSON object do not match.

Example

List all visible Elements:

GET  https://youruptime/api/v1/elements


GET /api/v1/elements/{id}

List a specific Element.

Returned Fields

For each returned Element the following fields are provided:

FieldTypeDescription
descriptionStringDescription of this Element.
groupIdIntegerID for this Element's parent Element group.
hostnameStringHostname used to contact this Element.
idIntegerID for this Element.
isMonitoredBooleanMonitoring status for this Element.
monitorsArrayAn array listing all monitors that belong to this Element (see Monitors Array below for details).
nameStringThe display name of this Element.
tagsArrayAn array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildrenArrayAn array listing all Elements that are a topological dependency of this Element in Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParentsArrayAn array listing all Elements that are topological parents of this Element in Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeNameString

A basic type definition for the Element. The following types are supported:

  • server
  • network device
  • Application
typeOsString

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.

typeSubtypeString

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
typeSubtypeNameString

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.

Monitors Array

The monitors array is the same across all end points. For each monitor associated with this Element the following fields are provided:

FieldTypeDescription
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor
Tags Array

For each tag or view associated with this Element, the following fields are provided:

FieldTypeDescription
idIntegerID of the tag or view
nameString

name of the tag or view

Topological Children Array

For each Element that is topologically dependent on this Element, the following fields are provided:

FieldTypeDescription
idIntegerID of the child Element
isMonitoredBooleanmonitoring status for the Element
nameStringname of the Element
Topological Parents Array

For each Element on which this Element is topologically dependent, the following fields are provided:

FieldTypeDescription
idIntegerID of the parent Element
isMonitoredBooleanmonitoring status for the Element
nameStringname of the Element

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1000Element Does Not Exist404

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 Uptime Infrastructure Monitor.

UT-1010Element Filter Expired410

The filter you are referencing is expired. Created filters persist, by default, for five minutes.

UT-1012Element Group Filter Expired410The group filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1013Invalid Element Filter400The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1015Invalid Element Group Filter400The 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-1028URL ID Body Mismatch400The Element ID in the URL and the JSON object do not match.

Example

List a specific Element (for example, ID #16):

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

Example: Determining an Element's Topological Parent

To determine the status of an Element's topological parent, refer to the Element listing's topologicalParents array. Consider the following example:

GET  https://youruptime/api/v1/elements/42

The response indicates this Element's parent, RDBuilds, has an ID of 40:

Use the status task on the Element (in this case, ID=40) to retrieve its status:

GET https://youruptime/api/ v1/elements/40/status


GET /api/v1/elements/{id}/status

Produces basic availability information, similar to the status shown on Global Scan. Using the standard API format, the status task can only be called against one Element at a time, based on ID:

GET  https://youruptime/api/v1/elements/<id>/status

Multiple Elements can first be filtered before calling by a status task. (See Filtering Objects for more information.)

Returned Fields

For the returned Element the following fields are provided:

FieldTypeDescription
idIntegerID for this service monitor
isMonitoredBooleanmonitoring status for this service monitor
lastCheckTimeString - Date Timethe last time this service monitor was executed successfully
lastTransitionTimeString - Date Timethe last time this service monitor changed status; this field can be used to determine time in the current status
messageStringthe output message produced the last time the service monitor was executed
nameStringdisplay name of this Element
powerStateStringthe current power state of the Element (only provided for virtual Elements; all other Elements return null)
statusStringthe last known status of this Element
monitorStatusArrayan array listing the status of all monitors related to this Element (see Monitor Status Arrays below for more detail)
topologyParentStatusArray

an array listing the status of all topological parent Elements that this Element is a child to (see Topology Status Arrays for more detail)

Note: this field is deprecated

masterMonitorsStatusArrayan array listing the status of all master service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail)
memberMonitorStatusArrayan array listing the status of all member service monitors, available if the Element type is an Application (see Monitor Status Arrays below for more detail

Monitor Status Arrays

The monitorStatus, masterMonitorStatus, and memberMonitorStatus arrays all provide the same response fields for each service monitor listed in the array:

FieldTypeDescription
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that Uptime Infrastructure Monitor uses, and can be ignored
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor
messageStringthe output message produced the last time the service monitor was executed
statusStringthe last known status of this service monitor
lastCheckTimeString - Date Timethe last time this service monitor was executed successfully
lastTransitionTimeString - Date Timethe last time this service monitor changed status; this field can be used to determine time in the current status

Topology Status Arrays

The topologyParentStatus array can be used to map topological dependency failures using identified parent child Element relationships.

Icon

Note: This field has is deprecated. You should instead use the topologicalChildren and topologicalParents arrays in an Element's specific listing.

FieldTypeDescription
idIntegerID for the parent Element
isMonitoredBooleanmonitoring status for the parent Element
lastCheckTimeString - Date Timethe last time the parent Element was checked successfully
lastTransitionTimeString - Date Timethe last time this parent Element changed status; this field can be used to determine time in the current status
messageStringthe output message produced the last time the parent's status changed
nameStringdisplay name of the parent Element
powerStateStringthe current power state of the parent Element (only provided for virtual Elements; all other Elements return null)
statusStringthe last known status of the parent Element

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1000Element Does Not Exist404

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 Uptime Infrastructure Monitor.

UT-1010Element Filter Expired410

The filter you are referencing is expired. Created filters persist, by default, for five minutes.

UT-1012Element Group Filter Expired410The group filter you are referencing is expired. Created filters persist, by default, for five minutes.
UT-1013Invalid Element Filter400The JSON used to create an Element filter is invalid, and could not be parsed. Check to ensure you are posting well-formed JSON.
UT-1015Invalid Element Group Filter400The 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-1028URL ID Body Mismatch400The Element ID in the URL and the JSON object do not match.

Example

GET  https://youruptime/api/v1/elements/1/status


PUT /api/v1/elements/{id}

JSON Request

The Element is updated based on fields defined in a JSON object. The Element ID is required, and any other field is used to update the Element configuration:

PropertyDescriptionRequirements
idthe id of the Element you want to update
  • required property
  • must match an Element ID
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • must be unique
  • maximum 50 characters
descriptiondescription for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe Element Group to which the Element belongs
  • must match valid groupId
  • end-user's user group is able to see the Element group
isMonitoredenables and disables monitoring for the Element, determining whether it appears in Global Scan and other dashboards
  • must be Boolean
Notes

In Uptime 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 Uptime Infrastructure Monitor Web interface (using the Element's Sync Display Name and Sync Hostname option).

If you move an Element into a new group, note that the Element inherits whichever associations the group may presently have, such as maintenance windows, service groups, or parent infrastructure groups; the Element likewise drops associations from the old group.

Disabling monitoring for a vCenter stops data collection for the vCenter host, and vCenter inventory objects such as clusters, resource pools, and vApps. Data collection for ESX hosts and VMs continue to occur.

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

UT-0200OK200Operation performed successfully.
UT-1000Element Does Not Exist404

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 Uptime Infrastructure Monitor.

UT-1002Element Group Does Not Exist400The referenced group ID does not exist.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1028URL ID Body Mismatch400The Element ID in the URL and the JSON object do not match.
UT-1029Duplicate Hostname200Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name200Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Setting this Element to isMonitored exceeds the current license.
UT-1040Spaces in Hostname

n/a
(JSON validation)

The Element hostname cannot contain whitespace.
UT-1041Proxy Error400This error can occur when your deployment includes a UI instance.
UT-1042HMC Violation400This error can occur when updating a pSeries-based Element that uses the HMC.
UT-1043Missing Fieldn/a
(JSON validation)
One or more of the Element ID, name, or hostname is missing.
UT-1044Field Number out of Range

n/a
(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a
(JSON validation)

One or more of the Element's name, description, or hostname exceed the maximum number of characters.

Examples

Change the display name, description, and hostname of an Element (for example, ID #3):

PUT https://youruptime/api/v1/elements/3

Disable monitoring for the same Element:

PUT https://youruptime/api/v1/elements/3

Move the Element from the default Infrastructure (with a groupId of 1) to another group:

PUT https://youruptime/api/v1/elements/3


POST /api/v1/elements (Agent server)

JSON Request

The Element is created based on fields defined in a JSON object. Most of the following fields must be provided (refer to the Requirements column for information); any additional fields are ignored:

PropertyDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe 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)
collectionMethodarray of data-collection properties describing how 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 Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Credentials Settings

if true, all other connection properties are ignored

  • defaults to false if property is not defined
portthe port through which the Uptime Infrastructure Monitor Agent communicates with the Monitoring Station
  • required if useGlobalConnectionSettings property is false
  • must be a valid port number (default 9998)
useSSLBoolean indicating whether the Uptime Infrastructure Monitor Agent securely communicates with the Monitoring Station using SSL
  • required if useGlobalConnectionSettings property is false
  • must be Boolean

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Error Code

Error

HTTP Code

Details

 OK200Operation performed successfully.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1029Duplicate Hostname400Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name400Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Adding this Element exceeds the current license.
UT-1035Add Element Error400An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1037Duplicate VMware UUID400The Element added already exists as part of the VMware vCenter inventory.
UT-1040Spaces in Hostname

n/a
(JSON validation)

The Element hostname cannot contain whitespace.
UT-1043Missing Fieldn/a
(JSON validation)
One or more of the Element ID, name, hostname, or group ID is missing.
UT-1044Field Number out of Range

n/a
(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a
(JSON validation)

One or more of the Element's name, description, or hostname exceed the maximum number of characters.

Example

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


POST /api/v1/elements (WMI server)

JSON Request

The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe 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)
collectionMethodarray of data-collection properties describing how 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 Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Credentials Settings

if true, all other connection properties are ignored

  • defaults to false if property is not defined
wmiDomainthe Windows domain in which WMI is implemented
  • required if useGlobalConnectionSettings property is false
wmiUsernamethe 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

Icon

the plain-text password is passed to Uptime Infrastructure Monitor using an encrypted connection

  • required if useGlobalConnectionSettings property is false

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Error Code

Error

HTTP Code

Details

 OK200Operation performed successfully.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1029Duplicate Hostname400Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name400Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Adding this Element exceeds the current license.
UT-1035Add Element Error400An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1037Duplicate VMware UUID400The Element added already exists as part of the VMware vCenter inventory.
UT-1040Spaces in Hostname

n/a
(JSON validation)

The Element hostname cannot contain whitespace.
UT-1043Missing Fieldn/a
(JSON validation)
One or more of the Element ID, name, hostname, or group ID is missing.
UT-1044Field Number out of Range

n/a
(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a
(JSON validation)

One or more of the Element's name, description, or hostname exceed the maximum number of characters.
UT-1034WMI Not Supported400You are most likely trying to add a WMI-based Element to a non-Windows host.

Example

Add a server whose metrics are reported via WMI:


POST /api/v1/elements (Hyper-V Server)

JSON Request

The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique
  • maximum 255 characters
  • contains no whitespace characters
groupidthe 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)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

  • agent
  • wmi
  • Snmp
  • hyperv
  • required property
  • must match one of the element connection methods (in this case, hyperv )
useGlobalConnectionSettings

Boolean determining whether the 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
hypervDomainthe Windows domain in which WMI is implemented
  • required if useGlobalConnectionSettings is false
hypervUsernamethe name of the account with access to WMI on the Windows domain
  • required if useGlobalConnectionSettings is false
hypervPassword

the password for the username above

the plaint-text password is passed to Uptime Infrastructure Monitor using an encrypted connection

  • required if useGlobalConnectionSettings is false

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Error CodeErrorHTTP CodeDetails
 OK200Operation performed successfully.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1029Duplicate Hostname400Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name400Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Adding this Element exceeds the current license.
UT-1035Add Element Error400An exception occurred when trying to add the Element. Could not add Hyper-V Server: This server has already been added.
UT-1040Spaces in Hostnamen/a
(JSON validation)
The Element hostname cannot contain whitespace.
UT-1043Missing Field

n/a

(JSON validation)

One or more of the Element ID, name, hostname, or group ID is missing.
UT-1044Field Number out of Range

n/a

(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a

(JSON validation)

One or more of the Element's name, description, or hostname exceeds the maximum number of characters.
UT-1034WMI Not Supported400You are most likely trying to add a WMI-based Element to a non-Windows host.

Example

Add a Hyper-V server whose metrics are reported via WMI:

After the Hyper-V Host is successfully added, please perform following steps:

  1. In Uptime Infrastructure Monitor, click Infrastructure.
  2. View the newly added Hyper-V Host Server.
  3. Edit the Sync settings to turn on Collect Virtual Machine data.
  4. Uptime Infrastructure Monitor starts collecting Guest VMs data.
Icon

All the existing service requests detailed out in this topic will work for Hyper-V with the addition of newly created, above mentioned POST service request.

 


POST /api/v1/elements (SNMP v2 Network Device)

JSON Request

The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property  
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe 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)
collectionMethodarray of data-collection properties describing how 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 Credentials 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)
snmpPortthe port on which the device is listening
  • required if useGlobalConnectionSettings is false
  • must be a valid port number (default 161)
snmpV2ReadCommunitythe SNMP community to use for the connection, typically set to public
  • required if useGlobalConnectionSettings is false
isPingabledetermines whether Uptime Infrastructure Monitor can contact the device using the ping utility
  • required if useGlobalConnectionSettings is false
  • must be Boolean

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Error Code

Error

HTTP Code

Details

 OK200Operation performed successfully.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1029Duplicate Hostname400Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name400Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Adding this Element exceeds the current license.
UT-1035Add Element Error400An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1040Spaces in Hostname

n/a
(JSON validation)

The Element hostname cannot contain whitespace.
UT-1043Missing Fieldn/a
(JSON validation)
One or more of the Element ID, name, hostname, or group ID is missing.
UT-1044Field Number out of Range

n/a
(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a
(JSON validation)

One or more of the Element's name, description, or hostname exceed the maximum number of characters.

Example

Add an SNMP v2 network device:


POST /api/v1/elements (SNMP v3 Network Device)

JSON Request

The Element is created based on fields defined in a JSON object. All of the following fields must be provided, and any additional fields are ignored:

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique  
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe 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)
collectionMethodarray of data-collection properties describing how 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 Credentials 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)
snmpPortthe port on which the device is listening
  • required if useGlobalConnectionSettings is false
  • must be a valid port number (default 161)
snmpV3Usernamethe name required to connect to the network device
  • required if useGlobalConnectionSettings is false
snmpV3AuthenticationPassword

the password required to connect to the network device

Icon

the plain-text password is passed to Uptime Infrastructure Monitor using an encrypted connection

  • required if useGlobalConnectionSettings is false
snmpV3AuthenticationMethod

determines how encrypted data moving between the network device and 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 Uptime Infrastructure Monitor

Icon

the plain-text password is passed to Uptime Infrastructure Monitor using an encrypted connection

  • required if useGlobalConnectionSettings is false
snmpV3PrivacyType

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

  • DES
  • AES
  • required if useGlobalConnectionSettings is false
  • must match one of the valid privacy types
isPingabledetermines whether Uptime Infrastructure Monitor can contact the device using the ping utility
  • required if useGlobalConnectionSettings is false
  • must be Boolean

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Error Code

Error

HTTP Code

Details

 OK200Operation performed successfully.
UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1029Duplicate Hostname400Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030Duplicate Element Name400Another Element (which you may not have permission to view) already exists with this display name.
UT-1033License Violation400Adding this Element exceeds the current license.
UT-1035Add Element Error400An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1040Spaces in Hostname

n/a
(JSON validation)

The Element hostname cannot contain whitespace.
UT-1043Missing Fieldn/a
(JSON validation)
One or more of the Element ID, name, hostname, or group ID is missing.
UT-1044Field Number out of Range

n/a
(JSON validation)

The declared Element group ID needs to be equal to or greater than 1.
UT-1045Field Too Long

n/a
(JSON validation)

One or more of the Element's name, description, or hostname exceed the maximum number of characters.

Example

Add an SNMP v3 network device:


DELETE /api/v1/elements/{id}

Delete an Element. No content is returned.

Notes on vCenter Elements

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

  • deleting a monitored VM through the API marks it as ignored
  • deleting an ignored VM through the API returns an error
  • deleting an ESX host that is part of a cluster returns an error

Response Codes

The following common response codes may result from this operation:

Response CodeCode DescriptionHTTP Status CodeDetails
UT-0400Bad Request400

The request could not be processed by the server due to incorrect syntax.

API commands can be accessed with this format:

https://<hostname>:<port>/api/<api_version>/<end_point>/<id>/<task>

If you encounter this error, ensure the referencing URL is correct.

UT-0404Resource Not Found404The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405Method Not Allowed405

The user does not have permission to perform the requested action. The user's Uptime Infrastructure Monitor permissions (for example, not permitted to Add Elements, Edit, or Delete Elements) stops them from doing the same though the API (POST, PUT, DELETE, respectively).

UT-0500Unknown500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. View the uptime_controller.log file for possible issues.

UT-0555Unknown Exception500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception has occurred; as a starting point, look for this exception in the uptime_controller.log file.

UT-0560Internal Server Error500

The corresponding HTTP error code (500) is a catch-all error generated by the Web server where an unexpected condition prevented fulfilling the request. In this case, an exception caused a stack trace; as a starting point, look for this stack trace in the uptime_controller.log file.

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 No Content204Operation performed successfully.
UT-1000Element Does Not Exist404

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 Uptime Infrastructure Monitor.

UT-1025Invalid Request Body JSON400The JSON object is not well formed.
UT-1026VM Not Deleted403

VMs and ESX hosts that are ignored cannot be deleted.

UT-1027Element Not Deleted403You are trying to delete an ESX host that is part of a cluster.
UT-1032Manual Monitor Not Deleted403Manually monitored hosts cannot be deleted.

Example

Delete a specific Element (for example, ID #16):

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

Additional references:


Save

  • No labels