Page History

...

Section

Column

width	10px

Column

width	25px

POST
POST
POST
POST
POST

 DELETE

Column

width	500px

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

...

Anchor
getElements
getElements
GET /api/v1/elements

...

For each returned Element the following fields will be are provided:

Field	Type	Description
description	String	Description of this Element.
groupId	Integer	ID for this ElementsElement's parent Element group.
hostname	String	Hostname used to contact this Element.
id	Integer	ID for this Element.
isMonitored	Boolean	Monitoring status for this Element.
monitors	Array	An array listing all monitors that belong to this Element (see Monitors Array below for details).
name	String	The display name of this Element.
tags	Array	An array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildren	Array	An array listing all Elements that are a topological dependency of this Element in up.time Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParents	Array	An array listing all Elements that are topological parents of this Element in up.time Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeName	String	A basic type definition for the Element. The following types are supported: server network device Application
typeOs	String	Returns basic operating system information for this Element: server: operating system network device: `sysDescr` value Application: no result will be 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.

...

The monitors array is the same across all end points. For each monitor associated with this Element the following fields will be 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 up.time Uptime Infrastructure Monitor uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

...

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

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

...

For each Element that is topologically dependent on this Element, the following fields will be 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

...

For each Element on which this Element is topologically dependent, the following fields will be 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

...

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 has is expired. Created filters persist, by default, for 5 five minutes.
UT-1013	Invalid Element Filter	400	The JSON being 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.

...

List all visible Elements:

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

Code Block

[
  {
      "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"
  },

   ...

]

...

For each returned Element the following fields will be are provided:

Field	Type	Description
description	String	Description of this Element.
groupId	Integer	ID for this ElementsElement's parent Element group.
hostname	String	Hostname used to contact this Element.
id	Integer	ID for this Element.
isMonitored	Boolean	Monitoring status for this Element.
monitors	Array	An array listing all monitors that belong to this Element (see Monitors Array below for details).
name	String	The display name of this Element.
tags	Array	An array listing all views/tags that this Element belongs to (see Tags Array below for details).
topologicalChildren	Array	An array listing all Elements that are a topological dependency of this Element in up.time Uptime Infrastructure Monitor (see Topological Children Array below for details).
topologicalParents	Array	An array listing all Elements that are topological parents of this Element in up.time Uptime Infrastructure Monitor (see Topological Parents Array below for details).
typeName	String	A basic type definition for the Element. The following types are supported: server network device Application
typeOs	String	Returns basic operating system information for this Element: server: operating system network device: `sysDescr` value Application: no result will be 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.

...

The monitors array is the same across all end points. For each monitor associated with this Element the following fields will be 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 up.time Uptime Infrastructure Monitor uses, and can generally be ignored
isMonitored	Boolean	monitoring status for the service monitor
name	String	name of the service monitor

...

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

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

...

For each Element that is topologically dependent on this Element, the following fields will be 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

...

For each Element on which this Element is topologically dependent, the following fields will be 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

...

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 have been be omitted, was inputted incorrectly, or is ignored in up.timeUptime Infrastructure Monitor.
UT-1010	Element Filter Expired	410	The filter you are referencing has is expired. Created filters persist, by default, for 5 five minutes.
UT-1012	Element Group Filter Expired	410	The group filter you are referencing has is expired. Created filters persist, by default, for 5 five minutes.
UT-1013	Invalid Element Filter	400	The JSON being 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 being 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.

...

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

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

Code Block

{
    "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"
}

...

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:

...

Code Block

{
    "id": 40,
    "isMonitored": true,
    "lastCheckTime": "20142016-01-15T09:07:45",
    "lastTransitionTime": "20142016-01-14T22:22:05",
    "message": "",
    "monitorStatus": [
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 133,
        "isAcknowledged": false,
        "isHidden": false,
        "isHostCheck": false,
        "isMonitored": true,
        "lastCheckTime": "20142016-01-15T09:08:58",
        "lastTransitionTime": "20142016-01-14T22:18:18",
        "message": "up.timeuptime agent running on RDBuilds, up.timeuptime 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": "20142016-01-15T09:08:25",
        "lastTransitionTime": "20142016-01-14T22:22:45",
        "message": "Information received from Agent: up.timeuptime 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": "20142016-01-15T09:07:45",
        "lastTransitionTime": "20142016-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": "20142016-01-15T03:45:01",
        "lastTransitionTime": "20142016-01-15T03:45:01",
        "message": "Information received from Agent: up.timeuptime agent 5.3.0 (build 3) linux ",
        "name": "Configuration Update Gatherer",
        "status": "OK"
        }
    ],
    "name": "RDBuilds",
    "powerState": null,
    "status": "OK",
    "topologyParentStatus": []
}

...

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 being called calling by a status task. (See Filtering Objects for more information.)

...

For the returned Element the following fields will be 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 will 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 has been 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

...

Field	Type	Description
elementId	Integer	ID of the Element this monitor is related to
id	Integer	ID of the service monitor
isHidden	Boolean	hidden monitors are internal monitors that up.time Uptime Infrastructure Monitor uses, and can generally 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

...

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

Info
Note: This field has been 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 will return null)
status	String	the last known status of the parent Element

...

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 have been be omitted, was inputted incorrectly, or is ignored in up.timeUptime Infrastructure Monitor.
UT-1010	Element Filter Expired	410	The filter you are referencing has is expired. Created filters persist, by default, for 5 five minutes.
UT-1012	Element Group Filter Expired	410	The group filter you are referencing has is expired. Created filters persist, by default, for 5 five minutes.
UT-1013	Invalid Element Filter	400	The JSON being 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 being 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

Code Block

{
   "id": 1,
   "isMonitored": true,
   "lastCheckTime": "20122016-09-17T14:13:56",
   "lastTransitionTime": "20122016-09-13T11:34:38",
   "message": "",
   "monitorStatus": 
   [
      {
         "elementId": 1,
         "id": 7,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "20122016-09-17T14:13:56",
         "lastTransitionTime": "20122016-09-17T14:05:56",
         "message": "",
         "name": "Default File System Capacity",
         "status": "UNKNOWN"
      },
      {
         "elementId": 1,
         "id": 8,
         "isHidden": false,
         "isHostCheck": false,
         "isMonitored": true,
         "lastCheckTime": "20122016-09-17T14:13:56",
         "lastTransitionTime": "20122016-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": "20122016-09-17T14:14:17",
         "lastTransitionTime": "20122016-09-13T11:34:24",
         "message": "",
         "name": "rd-vc2",
         "powerState": null,
         "status": "OK"
      },
      {
         "id": 15,
         "isMonitored": true,
         "lastCheckTime": "20122016-09-17T14:09:33",
         "lastTransitionTime": "20122016-09-13T11:34:32",
         "message": "",
         "name": "vmh-rd6.rd.local",
         "powerState": "On",
         "status": "OK"
      }
   ]
}

...

Anchor
putElementsId
putElementsId
PUT /api/v1/elements/{id}

JSON Request

The Element will be is updated based on fields defined in a JSON object. The Element ID is required, and any other field will be 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 up.time Uptime Infrastructure Monitor Web interface	must be unique maximum 50 characters
description	description for the Element	maximum 255 characters
hostname	resolvable network hostname or IP address of the Element	must be unique maximum 255 characters contains no whitespace characters
groupId	the Element Group to which the Element belongs to	must match valid `groupId` end-user's user group is able to see the Element group
isMonitored	enables and disables monitoring for the Element, determining whether it appears in Global Scan and other dashboards	must be Boolean

Notes

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

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

Disabling monitoring for a vCenter will stop 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 will continue to occur.

Response Codes

...

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 have been be omitted, was inputted incorrectly, or is ignored in up.timeUptime 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` will exceed 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.

...

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

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

Code Block
{ "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

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

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

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

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

...

Anchor
postElementsAgentServer
postElementsAgentServer
POST /api/v1/elements (Agent server)

JSON Request

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

...

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 will exceed 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 being 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 up.time Uptime Infrastructure Monitor Agent installed for data collection:

...

Anchor
postElementsWmiServer
postElementsWmiServer
POST /api/v1/elements (WMI server)

JSON Request

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

Field Description Requirements

name

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

required property
must be unique
maximum 50 characters

description

optional description for the Element

maximum 255 characters

hostname

resolvable network hostname or IP address of the Element

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

groupId

the Element Group the Element will be is placed in upon creation

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

type

the basic Element type:

Server
Network Device

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

collectionMethod

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

required property

connectionType

the connection method for the Element:

agent
wmi
snmp

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

useGlobalConnectionSettings

Boolean determining whether the up.time Uptime Infrastructure Monitor Agent Global Configuration has been is enabled in Global Element 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 has been is implemented

required if useGlobalConnectionSettings property is false

wmiUsername

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

required if useGlobalConnectionSettings property is false

wmiPassword

the password for the username above

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

required if useGlobalConnectionSettings property is false

...

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 will exceed 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 being 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.

...

Add a server whose metrics will be are reported via WMI:

Code Block

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

...

Anchor
postElementsHyperVServer
postElementsHyperVServer
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:

Include Page

	Common Error Codes
	Common Error Codes

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:

Code Block

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.

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

...

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

JSON Request

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

up.time

Field	Description	Requirements
name	display name for the Element anywhere in the up.time Uptime Infrastructure Monitor Web interface	required property must be unique maximum 50 characters
description	optional description for the Element	maximum 255 characters
hostname	resolvable network hostname or IP address of the Element	required property must be unique maximum 255 characters contains no whitespace characters
groupId	the Element Group the Element will be is placed in upon creation	required property must match valid `groupId` end-user's user group is able to see the Element group
type	the basic Element type: Server Network Device	required property must match one of the basic Element types (in this case, `Server`)
collectionMethod	array of data-collection properties describing how up.time will communicate 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 have been are set in Global Element 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:

...

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 will exceed 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:

...

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

JSON Request

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

Field Description Requirements

name

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

required property
must be unique
maximum 50 characters

description

optional description for the Element

maximum 255 characters

hostname

resolvable network hostname or IP address of the Element

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

groupId

the Element Group the Element will be is placed in upon creation

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

type

the basic Element type:

Server
Network Device

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

collectionMethod

array of data-collection properties describing how up.time will communicate 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 have been are set in Global Element 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

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

required if useGlobalConnectionSettings is false

snmpV3AuthenticationMethod

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

MD5
SHA

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

snmpV3PrivacyPassword

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

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

required if useGlobalConnectionSettings is false

snmpV3PrivacyType

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

DES
AES

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

isPingable

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

required if useGlobalConnectionSettings is false
must be Boolean

Response Codes

The following common response codes may result from this operation:

...

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 will exceed 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:

...

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

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

Response Codes

The following common response codes may result from this operation:

...

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 have been be omitted, was inputted incorrectly, or is ignored in up.timeUptime Infrastructure Monitor.
UT-1025	Invalid Request Body JSON	400	The JSON object is not well formed.
UT-1026	VM Not Deleted	403	VMs and ESX hosts that have been 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

Versions Compared

Old Version 2

New Version Current

Key

Anchor
getElements
getElements
GET /api/v1/elements

Example

Anchor
putElementsId
putElementsId
PUT /api/v1/elements/{id}

JSON Request

Notes

Response Codes

Anchor
postElementsAgentServer
postElementsAgentServer
POST /api/v1/elements (Agent server)

JSON Request

Example

Anchor
postElementsWmiServer
postElementsWmiServer
POST /api/v1/elements (WMI server)

JSON Request

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

Response Codes

Example

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

JSON Request

Response Codes

Example

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

JSON Request

Response Codes

Example

Response Codes

Example

Additional references:

Page tree

Page History

Versions Compared

Old Version 2

New Version Current

Key

AnchorgetElementsgetElementsGET /api/v1/elements

Example

AnchorputElementsIdputElementsIdPUT /api/v1/elements/{id}

JSON Request

Notes

Response Codes

AnchorpostElementsAgentServerpostElementsAgentServerPOST /api/v1/elements (Agent server)

JSON Request

Example

AnchorpostElementsWmiServerpostElementsWmiServerPOST /api/v1/elements (WMI server)

JSON Request

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

Response Codes

Example

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

JSON Request

Response Codes

Example

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

JSON Request

Response Codes

Example

Response Codes

Example

Additional references:

Anchor
getElements
getElements
GET /api/v1/elements

Anchor
putElementsId
putElementsId
PUT /api/v1/elements/{id}

Anchor
postElementsAgentServer
postElementsAgentServer
POST /api/v1/elements (Agent server)

Anchor
postElementsWmiServer
postElementsWmiServer
POST /api/v1/elements (WMI server)

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

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

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