Versions Compared

Old Version 5

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

Saved on

compared with

New Version 6

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

Saved on

Key

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

...

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

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

  • server
  • network device
  • Application
typeOsString

Returns basic operating system information for this Element:

  • server: operating system
  • network device: sysDescr value
  • Application: no result is returned

Elements of other types are not currently supported by the API.

typeSubtypeString

Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported:

  • server
    • AIX
    • Linux
    • Netware
    • Solaris
    • Windows
    • Hpux
    • EsxServer
    • IbmPowerSystems
    • VcenterServer
    • VcenterHostSystem
    • Unknown
  • network device
    • switch
  • Application
    • Application
typeSubtypeNameString

Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes.

...

FieldTypeDescription
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor

...

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1010Element Filter Expired410

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

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

...

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

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

  • server
  • network device
  • Application
typeOsString

Returns basic operating system information for this Element:

  • server: operating system
  • network device: sysDescr value
  • Application: no result is returned

Elements of other types are not currently supported by the API.

typeSubtypeString

Basic type information for this Element. This value should be used for matching Elements based on subtype. The following subtypes are supported:

  • server
    • AIX
    • Linux
    • Netware
    • Solaris
    • Windows
    • Hpux
    • EsxServer
    • IbmPowerSystems
    • VcenterServer
    • VcenterHostSystem
    • Unknown
  • network device
    • switch
  • Application
    • Application
typeSubtypeNameString

Detailed descriptions of the subtype, ideally used for display purposes. The values provided for this field are open to change and should not be used for matching purposes.

...

FieldTypeDescription
elementIdIntegerID of the Element this monitor is related to
idIntegerID of the service monitor
isHiddenBooleanhidden monitors are internal monitors that up.time uses, and can generally be ignored
isMonitoredBooleanmonitoring status for the service monitor
nameStringname of the service monitor

...

Other response codes that may occur include the following:

Response Code

Code Description

HTTP Status Code

Details

 OK200Information retrieved successfully.
UT-1000Element Does Not Exist404

A specifically referenced Element ID does not exist.

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

The element id '12345' does not exist.

The Element ID endpoint may be omitted, was inputted incorrectly, or is ignored in up.time.

UT-1010Element Filter Expired410

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

UT-1012Element Group Filter Expired410The group filter you are referencing has is expired. Created filters persist, by default, for 5 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.

...

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

...

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

...

Info

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

...

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

UT-1010Element Filter Expired410

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

UT-1012Element Group Filter Expired410The group filter you are referencing has is expired. Created filters persist, by default, for 5 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.

...

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

...

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

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.

...

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