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

...

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

   ...

]

...

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:

...

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

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

Code Block

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

...

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

Code Block

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

...

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.

...

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 }

...

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

...

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 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 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 Uptime Infrastructure Monitor using an encrypted connection

required if useGlobalConnectionSettings property is false

...

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:

groupIdsnmp Element snmp

the SNMP version used to connect to the network device:

v2

v3

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 SNMP Configuration Settings are set 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	snmpVersion		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
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, 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 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:

...

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

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

...

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:

...

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

Versions Compared

Old Version 9

New Version Current

Key

Anchor
getElements
getElements
GET /api/v1/elements

Example

Anchor

postElementsHyperVServer

postElementsHyperVServer
POST /api/v1/elements (

Hyper-V Server)

Response Codes

Example

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

JSON Request

Response Codes

Example

Response Codes

Example

Response Codes

Example

Additional references:

Page tree

Page History

Versions Compared

Old Version 9

New Version Current

Key

AnchorgetElementsgetElementsGET /api/v1/elements

Example

Anchor

postElementsHyperVServer

postElementsHyperVServerPOST /api/v1/elements (

Hyper-V Server)

Response Codes

Example

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

JSON Request

Response Codes

Example

Response Codes

Example

Response Codes

Example

Additional references:

Anchor
getElements
getElements
GET /api/v1/elements

postElementsHyperVServer
POST /api/v1/elements (

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