Working with Elements

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:

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

Update an Element configuration:

PUT

/api/v1/elements/{id}

Add or delete an Element:


          POST


            POST


              POST


              POST


                POST


          DELETE

/api/v1/elements (Agent Server) /api/v1/elements (WMI Server) /api/v1/elements (Hyper-V Server) /api/v1/elements (SNMP v2 Network Device) /api/v1/elements (SNMP v3 Network Device) /api/v1/elements/{id}

GET /api/v1/elements

List all Elements visible to the authenticated user account.

Returned Fields

For each returned Element the following fields are provided:

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

Monitors Array

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

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 Uptime Infrastructure Monitor uses, and can be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

Tags Array

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

Field	Type	Description
id	Integer	ID of the tag or view
name	String	name of the tag or view

Topological Children Array

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

Field	Type	Description
id	Integer	ID of the child Element
isMonitored	Boolean	monitoring status for the Element
name	String	name of the Element

Topological Parents Array

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

Field	Type	Description
id	Integer	ID of the parent Element
isMonitored	Boolean	monitoring status for the Element
name	String	name of the Element

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Information retrieved successfully.
UT-1010	Element Filter Expired	410	The 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-1028	URL ID Body Mismatch	400	The Element ID in the URL and the JSON object do not match.

Example

List all visible Elements:

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

[
  {
      "description": "QA Windows 2008 64bit",
      "groupId": 1,
      "hostname": "qa-w2k8-x64",
      "id": 1,
      "isMonitored": true,
      "monitors": [
          {
              "elementId": 1,
              "id": 55,
              "isHidden": true,
              "isMonitored": true,
              "name": "Configuration Update Gatherer"
          },
          {
              "elementId": 1,
              "id": 54,
              "isHidden": true,
              "isMonitored": true,
              "name": "Platform Performance Gatherer"
          },
          {
              "elementId": 1,
              "id": 52,
              "isHidden": false,
              "isMonitored": true,
              "name": "PING-qa-w2k8-x64"
          },
          {
              "elementId": 1,
              "id": 53,
              "isHidden": false,
              "isMonitored": true,
              "name": "UPTIME-qa-w2k8-x64"
          }
      ],
      "name": "qa-w2k8-x64",
      "tags": [ ],
      "topologicalChildren": [ ],
      "topologicalParents": [ ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "Windows Vista/Server 2008",
      "typeSubtype": "Windows",
      "typeSubtypeName": "Microsoft Windows"
  },

  ...

  {
      "description": null,
      "groupId": 1,
      "hostname": "vmh-rd7",
      "id": 8,
      "isMonitored": true,
      "monitors": [
          {
              "elementId": 8,
              "id": 180,
              "isHidden": true,
              "isMonitored": true,
              "name": "Advanced Platform Performance Gatherer"
          },
          {
              "elementId": 8,
              "id": 24,
              "isHidden": false,
              "isMonitored": true,
              "name": "PING-vmh-rd7"
          },
          {
              "elementId": 8,
              "id": 23,
              "isHidden": true,
              "isMonitored": true,
              "name": "Platform Performance Gatherer"
          },
          {
              "elementId": 8,
              "id": 179,
              "isHidden": true,
              "isMonitored": true,
              "name": "vSphere ESX Server Configuration Gatherer"
          }
      ],
      "name": "VMH RD7",
      "tags": [ ],
      "topologicalChildren": [ ],
      "topologicalParents": [
          {
              "id": 48,
              "isMonitored": true,
              "name": "VC4"
          }
      ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "VMware ESXi 5.1.0 build-1312873",
      "typeSubtype": "VcenterHostSystem",
      "typeSubtypeName": "VMware vSphere Server"
  },

  ...

  {
      "description": "VMware vCenter Server",
      "groupId": 1,
      "hostname": "rd-vc4",
      "id": 48,
      "isMonitored": true,
      "monitors": [
          {
              "elementId": 48,
              "id": 168,
              "isHidden": true,
              "isMonitored": true,
              "name": "Configuration Update Gatherer"
          },
          {
              "elementId": 48,
              "id": 167,
              "isHidden": true,
              "isMonitored": true,
              "name": "vCenter Health Check Monitor"
          },
          {
              "elementId": 48,
              "id": 166,
              "isHidden": true,
              "isMonitored": true,
              "name": "Storage Data Gatherer"
          },
          {
              "elementId": 48,
              "id": 165,
              "isHidden": true,
              "isMonitored": true,
              "name": "Platform Performance Gatherer"
          }
      ],
      "name": "VC4",
      "tags": [ ],
      "topologicalChildren": [
          {
              "id": 12,
              "isMonitored": true,
              "name": "VMH RD15"
          },
          {
              "id": 6,
              "isMonitored": true,
              "name": "VMH RD13"
          },

          ...

          {
              "id": 8,
              "isMonitored": true,
              "name": "VMH RD7"
          },
          {
              "id": 5,
              "isMonitored": true,
              "name": "VMH RD12"
          },
          {
              "id": 4,
              "isMonitored": true,
              "name": "VMH RD6"
          }
      ],
      "topologicalParents": [ ],
      "type": "Server",
      "typeName": "Server",
      "typeOs": "VMware vCenter Server 5.1.0 build-1364037",
      "typeSubtype": "VcenterServer",
      "typeSubtypeName": "VMware vCenter Server"
  },

   ...

]

GET /api/v1/elements/{id}

List a specific Element.

Returned Fields

For each returned Element the following fields are provided:

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

Monitors Array

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

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 Uptime Infrastructure Monitor uses, and can be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

Tags Array

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

Field	Type	Description
id	Integer	ID of the tag or view
name	String	name of the tag or view

Topological Children Array

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

Field	Type	Description
id	Integer	ID of the child Element
isMonitored	Boolean	monitoring status for the Element
name	String	name of the Element

Topological Parents Array

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

Field	Type	Description
id	Integer	ID of the parent Element
isMonitored	Boolean	monitoring status for the Element
name	String	name of the Element

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	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 Uptime 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.

Example

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

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

{
    "description": "QA Windows 2008 64bit",
    "groupId": 1,
    "hostname": "qa-w2k8-x64",
    "id": 16,
    "isMonitored": true,
    "monitors": [
        {
            "elementId": 16,
            "id": 54,
            "isHidden": true,
            "isMonitored": true,
            "name": "Platform Performance Gatherer"
        },
        {
            "elementId": 16,
            "id": 53,
            "isHidden": false,
            "isMonitored": true,
            "name": "UPTIME-qa-w2k8-x64"
        },
        {
            "elementId": 16,
            "id": 52,
            "isHidden": false,
            "isMonitored": true,
            "name": "PING-qa-w2k8-x64"
        },
        {
            "elementId": 16,
            "id": 55,
            "isHidden": true,
            "isMonitored": true,
            "name": "Configuration Update Gatherer"
        }
    ],
    "name": "qa-w2k8-x64",
    "tags": [ ],
    "topologicalChildren": [ ],
    "topologicalParents": [ ],
    "type": "Server",
    "typeName": "Server",
    "typeOs": "Windows Vista/Server 2008",
    "typeSubtype": "Windows",
    "typeSubtypeName": "Microsoft Windows"
}

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:

{
    "description": "uptime agent on production test with ssl (port 5556)",
    "groupId": 1,
    "hostname": "qa-agent01",
    "id": 42,
    "isMonitored": true,
    "monitors": [
        {
        "elementId": 42,
        "id": 141,
        "isHidden": false,
        "isMonitored": true,
        "name": "PING-qa-agent01"
        },
        {
        "elementId": 42,
        "id": 142,
        "isHidden": true,
        "isMonitored": true,
        "name": "Platform Performance Gatherer"
        },
        {
        "elementId": 42,
        "id": 144,
        "isHidden": true,
        "isMonitored": true,
        "name": "Configuration Update Gatherer"
        },
        {
        "elementId": 42,
        "id": 143,
        "isHidden": false,
        "isMonitored": true,
        "name": "UPTIME-qa-agent01"
        }
    ],
    "name": "qa-agent01.rd.local",
    "tags": [],
    "topologicalChildren": [],
    "topologicalParents": [
        {
        "id": 40,
        "isMonitored": true,
        "name": "RDBuilds"
        }
    ],
    "type": "Server",
    "typeName": "Server",
    "typeOs": "Red Hat Linux 5.2",
    "typeSubtype": "Linux",
    "typeSubtypeName": "Linux"
}

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

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

{
    "id": 40,
    "isMonitored": true,
    "lastCheckTime": "2016-01-15T09:07:45",
    "lastTransitionTime": "2016-01-14T22:22:05",
    "message": "",
    "monitorStatus": [
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 133,
        "isAcknowledged": false,
        "isHidden": false,
        "isHostCheck": false,
        "isMonitored": true,
        "lastCheckTime": "2016-01-15T09:08:58",
        "lastTransitionTime": "2016-01-14T22:18:18",
        "message": "uptime agent running on RDBuilds, uptime agent 5.3.0 (build 3) linux",
        "name": "UPTIME-RDBbuilds",
        "status": "OK"
        },
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 135,
        "isAcknowledged": false,
        "isHidden": true,
        "isHostCheck": false,
        "isMonitored": true,
        "lastCheckTime": "2016-01-15T09:08:25",
        "lastTransitionTime": "2016-01-14T22:22:45",
        "message": "Information received from Agent: uptime agent 5.3.0 (build 3) linux ",
        "name": "Platform Performance Gatherer",
        "status": "OK"
        },
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 134,
        "isAcknowledged": false,
        "isHidden": false,
        "isHostCheck": true,
        "isMonitored": true,
        "lastCheckTime": "2016-01-15T09:07:45",
        "lastTransitionTime": "2016-01-14T22:22:05",
        "message": "Ping completed: 5 sent, 0.0% loss, 0.4ms average round trip time",
        "name": "PING-RDBuilds",
        "status": "OK"
        },
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 136,
        "isAcknowledged": false,
        "isHidden": true,
        "isHostCheck": false,
        "isMonitored": true,
        "lastCheckTime": "2016-01-15T03:45:01",
        "lastTransitionTime": "2016-01-15T03:45:01",
        "message": "Information received from Agent: uptime agent 5.3.0 (build 3) linux ",
        "name": "Configuration Update Gatherer",
        "status": "OK"
        }
    ],
    "name": "RDBuilds",
    "powerState": null,
    "status": "OK",
    "topologyParentStatus": []
}

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:

Field	Type	Description
id	Integer	ID for this service monitor
isMonitored	Boolean	monitoring status for 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
message	String	the output message produced the last time the service monitor was executed
name	String	display name of this Element
powerState	String	the current power state of the Element (only provided for virtual Elements; all other Elements return null)
status	String	the last known status of this Element
monitorStatus	Array	an array listing the status of all monitors related to this Element (see Monitor Status Arrays below for more detail)
topologyParentStatus	Array	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
masterMonitorsStatus	Array	an 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)
memberMonitorStatus	Array	an 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:

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

Topology Status Arrays

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

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

Field	Type	Description
id	Integer	ID for the parent Element
isMonitored	Boolean	monitoring status for the parent Element
lastCheckTime	String - Date Time	the last time the parent Element was checked successfully
lastTransitionTime	String - Date Time	the last time this parent Element changed status; this field can be used to determine time in the current status
message	String	the output message produced the last time the parent's status changed
name	String	display name of the parent Element
powerState	String	the current power state of the parent Element (only provided for virtual Elements; all other Elements return null)
status	String	the last known status of the parent Element

Response Codes

The following common response codes may result from this operation:

Response Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	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 Uptime 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.

Example

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

{
   "id": 1,
   "isMonitored": true,
   "lastCheckTime": "2016-09-17T14:13:56",
   "lastTransitionTime": "2016-09-13T11:34:38",
   "message": "",
   "monitorStatus": 
   [
      {
         "elementId": 1,
         "id": 7,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "2016-09-17T14:13:56",
         "lastTransitionTime": "2016-09-17T14:05:56",
         "message": "",
         "name": "Default File System Capacity",
         "status": "UNKNOWN"
      },
      {
         "elementId": 1,
         "id": 8,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "2016-09-17T14:13:56",
         "lastTransitionTime": "2016-09-17T14:13:56",
         "message": "",
         "name": "Default Agent Service Check",
         "status": "UNKNOWN"
      },
      ...
   ],
   "name": "win-dleith",
   "powerState": "On",
   "status": "OK",
   "topologyParentStatus": 
   [
      {
         "id": 2,
         "isMonitored": true,
         "lastCheckTime": "2016-09-17T14:14:17",
         "lastTransitionTime": "2016-09-13T11:34:24",
         "message": "",
         "name": "rd-vc2",
         "powerState": null,
         "status": "OK"
      },
      {
         "id": 15,
         "isMonitored": true,
         "lastCheckTime": "2016-09-17T14:09:33",
         "lastTransitionTime": "2016-09-13T11:34:32",
         "message": "",
         "name": "vmh-rd6.rd.local",
         "powerState": "On",
         "status": "OK"
      }
   ]
}

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:

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 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 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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-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 Uptime Infrastructure Monitor.
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.

Examples

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

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

{
  "id": 3,
  "name": "pserv2",
  "description": "print server new location",
  "hostname": "10.1.1.100"
}

Disable monitoring for the same Element:

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

{
  "id": 3,
  "isMonitored": false
}

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

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

{
  "id": 3,
  "groupId": 2
}

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:

Property	Description	Requirements
name	display name for the Element anywhere in the 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 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
port	the 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)
useSSL	Boolean 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Operation performed successfully.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1029	Duplicate Hostname	400	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	400	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Adding this Element exceeds the current license.
UT-1035	Add Element Error	400	An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1037	Duplicate VMware UUID	400	The Element added already exists as part of the VMware vCenter inventory.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, hostname, or group ID 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.

Example

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

POST https://youruptime/api/v1/elements
{
  "name": "linux-apache1",
  "description": "apache demo server",
  "hostname": "apache1",
  "groupId": 1,
  "type": "Server",
  "collectionMethod": {
    "connectionType": "agent",
    "useGlobalConnectionSettings": false,
    "port": 9998,
    "useSSL": false
  }
}

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:

Field	Description	Requirements
name	display name for the Element anywhere in the 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 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
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 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Operation performed successfully.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1029	Duplicate Hostname	400	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	400	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Adding this Element exceeds the current license.
UT-1035	Add Element Error	400	An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1037	Duplicate VMware UUID	400	The Element added already exists as part of the VMware vCenter inventory.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, hostname, or group ID 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.
UT-1034	WMI Not Supported	400	You 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 https://youruptime/api/v1/elements
{
  "name": "Win7 agentless/WMI",
  "description": "Windows 7 Production",
  "hostname": "Win7-Production",
  "groupId": 1,
  "type": "Server",
  "collectionMethod": {
    "connectionType": "wmi",
    "useGlobalConnectionSettings": false,
    "wmiDomain": "windomain",
    "wmiUsername": "administrator",
    "wmiPassword": "password"
  }
}

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:

Field	Description	Requirements
name	display name for the Element anywhere in the 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 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
hypervDomain	the Windows domain in which WMI is implemented	required if `useGlobalConnectionSettings` is `false`
hypervUsername	the 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Operation performed successfully.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1029	Duplicate Hostname	400	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	400	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Adding this Element exceeds the current license.
UT-1035	Add Element Error	400	An exception occurred when trying to add the Element. Could not add Hyper-V Server: This server has already been added.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, hostname, or group ID 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 exceeds the maximum number of characters.
UT-1034	WMI Not Supported	400	You 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:

POST https://youruptime/api/v1/elements
{
  "name": "Win 7 Hyper-V Host Server",
  "description": "Windows 7 Production",
  "hostname": "Win7-Production",
  "groupId": 1,
  "type": "Server",
  "collectionMethod": {
    "connectionType": "hyperv",
    "useGlobalConnectionSettings": false,
    "hypervDomain": "windomain",
    "hypervUsername": "administrator",
    "hypervPassword": "password",
  }
}

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

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

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:

Field	Description	Requirements
name	display name for the Element anywhere in the 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 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`)
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 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Operation performed successfully.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1029	Duplicate Hostname	400	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	400	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Adding this Element exceeds the current license.
UT-1035	Add Element Error	400	An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, hostname, or group ID 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.

Example

Add an SNMP v2 network device:

POST https://youruptime/api/v1/elements
{
  "name": "gatewaySNMP",
  "description": "snmp v2",
  "hostname": "gateway.mydomain.com",
  "groupId": 1,
  "type": "Network Device",
  "collectionMethod": {
    "connectionType": "snmp",
    "useGlobalConnectionSettings": false,
    "snmpVersion": "v2",
    "snmpPort": "161",
    "snmpV2ReadCommunity": "myCo-pub",
    "isPingable": true
  }
}

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:

Field	Description	Requirements
name	display name for the Element anywhere in the 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 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`)
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 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 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
isPingable	determines 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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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
	OK	200	Operation performed successfully.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1029	Duplicate Hostname	400	Another Element (which you may not have permission to view) already exists with this hostname.
UT-1030	Duplicate Element Name	400	Another Element (which you may not have permission to view) already exists with this display name.
UT-1033	License Violation	400	Adding this Element exceeds the current license.
UT-1035	Add Element Error	400	An exception occurred when trying to add the Element. Verify the Element details, such as hostname, are correct.
UT-1040	Spaces in Hostname	n/a (JSON validation)	The Element hostname cannot contain whitespace.
UT-1043	Missing Field	n/a (JSON validation)	One or more of the Element ID, name, hostname, or group ID 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.

Example

Add an SNMP v3 network device:

POST https://youruptime/api/v1/elements
{
  "name": "gatewaySNMP",
  "description": "snmp v3",
  "hostname": "gateway.mydomain.com",
  "groupId": 1,
  "type": "Network Device",
  "collectionMethod": {
    "connectionType": "snmp",
    "useGlobalConnectionSettings": false,
    "snmpVersion": "v3",
    "snmpPort": "161",
    "snmpV3Username": "myUsername",
    "snmpV3AuthenticationPassword": "myPassword",
    "snmpV3AuthenticationMethod": "MD5",
    "snmpV3PrivacyPassword": "myOtherPassword",
    "snmpV3PrivacyType": "DES",
    "isPingable": true
  }
}

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 Code	Code Description	HTTP Status Code	Details
UT-0400	Bad Request	400	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-0404	Resource Not Found	404	The request could not be processed because an object is missing. The endpoint may be omitted from the command, or was spelled incorrectly.
UT-0405	Method Not Allowed	405	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-0500	Unknown	500	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-0555	Unknown Exception	500	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-0560	Internal Server Error	500	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 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 Uptime 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.

Example

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

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

Additional references:

Save

Page tree

Working with Elements

Summary

GET /api/v1/elements

Returned Fields

Monitors Array

Tags Array

Topological Children Array

Topological Parents Array

Response Codes

Example

GET /api/v1/elements/{id}

Returned Fields

Monitors Array

Tags Array

Topological Children Array

Topological Parents Array

Response Codes

Example

Example: Determining an Element's Topological Parent

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

Returned Fields

Monitor Status Arrays

Topology Status Arrays

Response Codes

Example

PUT /api/v1/elements/{id}

JSON Request

Notes

Response Codes

Examples

POST /api/v1/elements (Agent server)

JSON Request

Response Codes

Example

POST /api/v1/elements (WMI server)

JSON Request

Response Codes

Example

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

Response Codes

Example

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

JSON Request

Response Codes

Example

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

JSON Request

Response Codes

Example

DELETE /api/v1/elements/{id}

Notes on vCenter Elements

Response Codes

Example

Additional references: