Versions Compared

Old Version 8

changes.mady.by.user Unknown User (npollard)

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User (npollard)

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Section
Column
width10px

 

Column
width25px
POST
POST
POST
POST
POST
DELETE
Column
width500px

/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": "20152016-01-15T09:07:45",
    "lastTransitionTime": "20152016-01-14T22:22:05",
    "message": "",
    "monitorStatus": [
        {
        "acknowledgedComment": null,
        "elementId": 40,
        "id": 133,
        "isAcknowledged": false,
        "isHidden": false,
        "isHostCheck": false,
        "isMonitored": true,
        "lastCheckTime": "20152016-01-15T09:08:58",
        "lastTransitionTime": "20152016-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": "20152016-01-15T09:08:25",
        "lastTransitionTime": "20152016-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": "20152016-01-15T09:07:45",
        "lastTransitionTime": "20152016-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": "20152016-01-15T03:45:01",
        "lastTransitionTime": "20152016-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

 OK200Information retrieved successfully.
UT-1000Element Does Not Exist404

A specifically referenced Element ID does not exist.

In such a case, referencing  https://youruptime:9997/api/ v1/elements/12345 would return the following:

The element id '12345' does not exist.

The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor.

UT-1010Element Filter Expired410

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

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

Example

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

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

...

Response Code

Code Description

HTTP Status Code

Details

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

A specifically referenced Element ID does not exist.

In such a case, referencing  https://youruptime:9997/api/ v1/elements/12345 would return the following:

The element id '12345' does not exist.

The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor.

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

...

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
}

...

PropertyDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe Element Group the Element is placed in upon creation
  • required property
  • must match valid groupId
  • end-user's user group is able to see the Element group
type

the basic Element type:

  • Server
  • Network Device
  • required property
  • must match one of the basic Element types (in this case, Server)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

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

Boolean determining whether the Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Element Credentials Settings

if true, all other connection properties are ignored

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

...

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe Element Group the Element is placed in upon creation
  • required property
  • must match valid groupId
  • end-user's user group is able to see the Element group
type

the basic Element type:

  • Server
  • Network Device
  • required property
  • must match one of the basic Element types (in this case, Server)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

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

Boolean determining whether the Uptime Infrastructure Monitor Agent Global Configuration is enabled in Global Element Credentials Settings

if true, all other connection properties are ignored

  • defaults to false if property is not defined
wmiDomainthe Windows domain in which WMI is implemented
  • required if useGlobalConnectionSettings property is false
wmiUsernamethe name of the account with access to WMI on the Windows domain
  • required if useGlobalConnectionSettings property is false
wmiPassword

the password for the username above

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
FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property 
  • must be unique 
  • maximum 255 characters 
  • contains no whitespace characters
groupidthe Element Group the Element is placed in upon creation
  • required property
  • must match valid groupId
  • end-user's user group is able to see the Element group
type

the basic Element type:

  • Server
  • Network Device
  • required property
  • must match one of the basic Element types (in this case, Server)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

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

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

the password for the username above

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

  • required if useGlobalConnectionSettings is false

Response Codes

The following common response codes may result from this operation:

Include Page
Common Error Codes
Common Error Codes

Other response codes that may occur include the following:

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

n/a

(JSON validation)

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

n/a

(JSON validation)

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

n/a

(JSON validation)

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

Example

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

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:

  1. In Uptime Infrastructure Monitor, click Infrastructure.
  2. View the newly added Hyper-V Host Server.
  3. Edit the Sync settings to turn on Collect Virtual Machine data.
  4. Uptime Infrastructure Monitor starts collecting Guest VMs data.
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:

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property  
  • must be unique 
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe Element Group the Element is placed in upon creation
  • required property
  • must match valid groupId
  • end-user's user group is able to see the Element group
type

the basic Element type:

  • Server
  • Network Device
  • required property
  • must match one of the basic Element types (in this case, Server)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

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

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

if true, all other connection properties are ignored

  • defaults to false if property is not defined
snmpVersion

the SNMP version used to connect

snmpVersion

the SNMP version used to connect to the network device:

  • v2
  • v3
  • required if useGlobalConnectionSettings is false
  • must match one of the valid SNMP versions (in this case, v2)
snmpPortthe port on which the device is listening
  • required if useGlobalConnectionSettings is false
  • must be a valid port number (default 161)
snmpV2ReadCommunitythe SNMP community to use for the connection, typically set to public
  • required if useGlobalConnectionSettings is false
isPingabledetermines whether Uptime Infrastructure Monitor can contact the device using the ping utility
  • required if useGlobalConnectionSettings is false
  • must be Boolean

Response Codes

The following common response codes may result from this operation:

...

Other response codes that may occur include the following:

Error Code

Error

HTTP Code

Details

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

Example

Add an SNMP v2 network device:

...

FieldDescriptionRequirements
namedisplay name for the Element anywhere in the Uptime Infrastructure Monitor Web interface
  • required property
  • must be unique
  • maximum 50 characters
descriptionoptional description for the Element
  • maximum 255 characters
hostnameresolvable network hostname or IP address of the Element
  • required property
  • must be unique  
  • maximum 255 characters  
  • contains no whitespace characters
groupIdthe Element Group the Element is placed in upon creation
  • required property
  • must match valid groupId
  • end-user's user group is able to see the Element group
type

the basic Element type:

  • Server
  • Network Device
  • required property
  • must match one of the basic Element types (in this case, Server)
collectionMethodarray of data-collection properties describing how Uptime Infrastructure Monitor communicates with the Element
  • required property
connectionType

the connection method for the Element:

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

Boolean determining whether Global SNMP Configuration Settings are set in Global 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)
snmpPortthe port on which the device is listening
  • required if useGlobalConnectionSettings is false
  • must be a valid port number (default 161)
snmpV3Usernamethe name required to connect to the network device
  • required if useGlobalConnectionSettings is false
snmpV3AuthenticationPassword

the password required to connect to the network device

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
isPingabledetermines whether Uptime Infrastructure Monitor can contact the device using the ping utility
  • required if useGlobalConnectionSettings is false
  • must be Boolean

Response Codes

The following common response codes may result from this operation:

...

Error Code

Error

HTTP Code

Details

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

n/a
(JSON validation)

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

Example

Add an SNMP v3 network device:

...

  • 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 Content204Operation performed successfully.
UT-1000Element Does Not Exist404

A specifically referenced Element ID does not exist.

In such a case, referencing  https://youruptime:9997/api/ v1/elements/12345 would return the following:

The element id '12345' does not exist.

The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in Uptime Infrastructure Monitor.

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

VMs and ESX hosts that are ignored cannot be deleted.

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

Example

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

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

 

 

Additional references:


Save