Introduction

The Mutiny REST API represents the various elements that a Mutiny system contains as parts of a URL path and then allows HTTP verbs to be used to operate on them. In the following documentation :parameter in a URL is used to represent a parameter that the user should fill in. Data is returned as either a JSON document or as a Location header that should be used to retrieve another document. The trailing slash / is required when accessing collections of resources.

When modifying or adding data all parameters are optional except when noted. Standard HTTP status code are used to indicate success and failure (i.e. 200 - OK, 400 - Bad Request, 404 - Resource not found) If there was an error the resource body will contain a textual ID giving more information.

Basic Authentication is used to secure access to the API. Any user of the main Mutiny interface can access the API with the same set of permissions as normal.

Nodes

GET - /api/nodes/?outputFormat=default|concise|idsOnly|extended

Returns data about all the nodes on the system as an unsorted array of objects. The outputFormat argument is optional and can be used to change how much data is returned. The extended output format is required to return ICMP, interface and agent data.

GET - /api/nodes/?outputFormat=duplicates

Returns data about all the duplicates on the system as an unsorted array of arrays. Each array returned represents one set of duplicates. Nodes are treated as duplicates if their sysName matches and they have the same set of MAC address and IP address pairs.

GET - /api/nodes/:nodeid

Returns data about a single node as an object.

GET - /api/nodes/:nodeid/children/

Returns the IDs of the direct children of a single node as an array.

GET - /api/nodes/:nodeid/snmpInfo/

Returns SNMP info about a single node as an object.

GET - /api/nodes/:nodeid/systemDetails/

Returns system details (os, model etc.) about a single node as an object.

GET - /api/nodes/:nodeid/location

Returns Location info about a single node as an object or null if no Location has been set.

GET - /api/nodes/:nodeid/icmp/

Returns ICMP polling data for a single node as an object.

GET - /api/nodes/:nodeid/icmp/:address

Returns ICMP polling for a single address on a single node as an object.

GET - /api/nodes/:nodeid/interfaces/

Returns interface and address data about a single node as an object.

GET - /api/nodes/:nodeid/interfaces/:index

Returns interface and address data about a single interface on a single node as an object.

GET - /api/nodes/:nodeid/agents/

Returns Agent polling configuration for a single node as an object.

GET - /api/nodes/:nodeid/agents/

Returns all Agent polling data for a single node as a list of objects.

GET - /api/nodes/:nodeid/agents/:agentid

Returns Agent polling for a single agent on a single node as an object.

GET - /api/nodes/:nodeid/maintenanceMode

Returns maintenance mode settings for a single node as an object.

GET - /api/nodes/:nodeid/duplicates/

Returns any duplicates of the specified node as an array of objects. If there are no duplicates an empty array will be returned.

GET - /api/nodes/:nodeid/events/?startTime=aaa&endTime=bbb&page=ccc

Returns events that have occurred on a single node. The parameters the request takes are as follows:-

startTimeThe earliest timestamp for events to be closed. The timestamp can be specified in milliseconds since the Unix epoch or in ISO-8601 format. The default is to start 7 days earlier than the endTime.
endTimeThe latest timestamp for events to be opened. The timestamp can be specified in milliseconds since the Unix epoch or in ISO-8601 format. The default is the current time.
pageAt most 500 events will be returned for each request. To access more events this parameter can be used to select additional pages. The default is 0.

The returned data will be similar to the following format:-

[
    {
        "eventID": number,
        "state": "unconfirmed|open|closed|expired",
        "status": "critical|warning|unknown|ok|ignored|notPolled",
        "worstStatus": "critical|warning|unknown|ok|ignored|notPolled",
        "openTime": "...",      // ISO-8601 timestamp
        "closeTime": "...",     // Optional, ISO-8601 timestamp
        "item": {   // Optional
            "label": "...",
            "groupLabel": "..."
        },
        "acknowledged": {   // Optional
            "by": "...",
            "until": "..."  // ISO-8601 timestamp
        },
        "description": "...",
        "longDescription": "..."
    },
    {
        "eventID": number,
        ...
    },
    ...
]

GET - /api/nodes/:nodeid/graphData/

Returns data about all the sources of graphing data for a single node. Also returns the possible sub-types of the graphing data sources. The returned data will be in the following format:-

{
    "graphSources": {
        ":sourceid 1": {  // The source ID is required when requesting a set of graphing data.
            "type": "...",  // The type of the graphing source should be used to lookup which sub-types are available.
            "label": "..."
        },
        ":sourceid 2": {
            "type": "...",
            "label": "..."
        },
        ...
    },
    "subTypes": {
        "type 1": [
            {
                "id": "...",  // This ID should be used when requesting a set of graphing data.
                "label": "...",
                "multipleDataSets": true|false   // Whether the sub-type returns multiple datasets. For example the
                                                 //   interface usage type return data-sets for both input and output.
            },
            { },
            ...
        ],
        "type 2": [
            ...
        ],
        ...
    }
}

GET - /api/nodes/:nodeid/graphData/:sourceid?subType=aaa&maxPoints=bbb&startTime=ccc&endTime=yyy&calculateAggregates=zzz

Returns graphing data from a single source from a single node. The parameters the request takes are as follows:-

subTypeThe sub-type of graphing data to be returned (e.g. usage, used_space) The possible sub types are returned with the previous request and a sensible default will be chosen if omitted.
maxPointsThe maximum number of points to be returned. If more points are available the data will be down-sampled to fit. The default is to return a maximum of 500 points.
targetTimeStepThe desired time step in milliseconds or ISO-8601 duration format (e.g. PT30M) between points to be returned. If more points are available the data will be down-sampled to fit. If maxPoints is also specified then that parameter will override this one.
startTimeThe earliest timestamp for data to be returned. The timestamp can be specified in milliseconds since the Unix epoch or in ISO-8601 format. The default is to start duration time earlier than the endTime.
endTimeThe latest timestamp for data to be returned. The timestamp can be specified in milliseconds since the Unix epoch or in ISO-8601 format. The default is the current time.
durationThe duration between the starting and ending time to be returned. The timestamp can be specified in milliseconds or in ISO-8601 duration format. The default is 7 days and this parameter is ignored if both startTime and endTime are specified.
calculateAggregatesWhether aggregate values should be calculated and returned. If set to true minimum, maximum, average and least square regression values are calculated. The default is false.
calculatePercentileWhether 95% percentile values should be calculated and returned. The default is the same as the calculateAggregates parameter.
outputDataWhether data should be output and what format it should take. When set to csv CSV formatted data is returned. When set to false calculateAggregates is automatically turned on. The default is true.

The returned data will be similar to the following format by default:-

{
    "graphType": "...",
    "startTime": epoch milliseconds,
    "endTime": epoch milliseconds,
    "timeStamps": [epoch milliseconds 1, epoch milliseconds 2, ...],
    "values": [
        {
            "data": [number 1, number 2, ...],   // Array is same length as timeStamps array, absent values are represented as null.
            
            // Parameters below are optional
            "label": "...",
            "propertyTypeID": "...",
            "lowCritical": number,
            "lowWarning": number,
            "highWarning": number,
            "highCritical": number,
            "aggregateValues": {    // Absent values are represented as null.
                "average": number,
                "minimum": number,
                "maximum": number,
                "percentile95": number
            }
        },
        {
            ...
        },
        ...
    ],
    
    // Parameters below are optional
    "title": "...",  // description of graph, intended for display
    "subType": "...",
    "yAxis": {
        "label": "..." // intended for display
        "min": number,
        "max": number
    }
}

The returned data will be similar to the following format if outputData is set to csv or if the Accept header includes text/csv:-

"Mutiny System Data: Node ...Node Name..."
"Date","Label 1 (Units 1)","Label 2 (Units 2)",...
"25/01/2024 00:00:00","0.00000","0.00000",...
"26/01/2024 00:00:00","0.00000","0.00000",...

POST - /api/nodes/:nodeid

Updates a single node. The request body should contain a JSON document similar to:-

{
    "label": "New Label",
    "polling": "all|ignore_connectivity|none",
    "alerts": true|false,    // Enables and disables all alerts for this Node
    "address": "New IP v4 address",
    "parentID": "ID of new parent node",
    "maintenanceMode": {
        "state": "off|alerts_only|alerts_events",    // Required if maintenanceMode object is provided.
        "type": "until_ok|timed",   // Whether the maintenance mode should end at a certain time or when the node becomes OK, defaults to timed.
        "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when setting a timed maintenance mode
    },
    "panelDefinitionID": "uuid",            // The ID of the panel definition to use for this node.
    "clearPanelDefinition": true|false,     // Whether to clear the panel definition for this node, is ignored if panelDefinitionID is provided.
}

All parameters are optional except where noted.

POST - /api/nodes/:nodeid/maintenanceMode

Updates the maintenance mode settings for a single node. The request body should contain a JSON document similar to:-

{
    "state": "off|alerts_only|alerts_events",    // Required.
    "type": "until_ok|timed",   // Whether the maintenance mode should end at a certain time or when the node becomes OK, defaults to timed.
    "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when setting a timed maintenance mode
}

POST - /api/nodes/:nodeid/location

Updates the Location for a single node. The request body should contain one of the following values:-

  • ...integer... - ID of the new Location
  • ...string... - Name of the new Location
  • false - Removes the Location from the node

POST - /api/nodes/:nodeid/icmp/:address

Updates the ICMP polling settings for a single node. The :address parameter can be either an IP address present on the node or * to update all IP addresses. The request body should contain a JSON document similar to:-

{
    "polled": true|false    // Required.
}

POST - /api/nodes/:nodeid/interfaces/:index

Updates the interface polling settings for a single node. The :index parameter can be either the numeric index number for a single interface or * to update all interfaces. The request body should contain a JSON document similar to:-

{
    "polling": {
        "polled": true|false,                // Defaults to no change if omitted.
        "condition": {
            "ignoreConnectivity": true|false // Defaults to no change if omitted.
        },
        "traffic": {
            "ignoreUsage": true|false,      // Defaults to no change if omitted.
            "input": {
                "critical": number,         // Required if threshold is set, between 0 and 100%
                "warning": number,          // Required if threshold is set, between 0 and 100%
                "lowerLimit": true|false    // Defaults to false
            },
            "output": {
                "critical": number,         // Required if threshold is set, between 0 and 100%
                "warning": number,          // Required if threshold is set, between 0 and 100%
                "lowerLimit": true|false    // Defaults to false
            }
        }
    }
}

All parameters are optional except where noted.

POST - /api/nodes/:nodeid/agents

Updates the agent polling settings for a single node. The request body should contain a JSON document similar to:-

{
    "polling": {
        "polled": true|false
    }
}

All parameters are optional except where noted.

PUT - /api/nodes/:nodeid/agents/:agentid

Adds a single agent to the specified node. If an adapter is associated with this agent it will also be added.

DELETE - /api/nodes/:nodeid?deleteDescendants=true|false

Deletes a single node. If deleteDescendants is true then all descendant nodes will also be deleted. Warning: a large amount of data can be deleted very quickly if a high level node and its descendants are deleted.

DELETE - /api/nodes/:nodeid/agents/:agentid

Deletes a single agent from the specified node. If an adapter is associated with this agent it will also be removed.

Views

GET - /api/views/

Returns data about all the views on the system as an unsorted array of objects.

POST - /api/views/

Adds a view to the system. The request body should contain a JSON document similar to:-

{
    "label": "New Label",       // Required
    "published": true|false,
    "drawHierarchy": true|false,
    "iconSet": "See Icon Set Values",
    "parentID": "ID of parent view",
    "childNodes": ["Node ID 1", "Node ID 2", ...]
}

Returns a Location header and a JSON document for the new view.

GET - /api/views/:viewid

Returns data about a single view as an object.

POST - /api/views/:viewid

Updates a single view. The request body should contain a JSON document similar to:-

{
    "label": "New Label",
    "published": true|false,
    "drawHierarchy": true|false,
    "iconSet": "See Icon Set Values",
    "parentID": "ID of parent view"     // Note: Setting parentID to a boolean false moves the view to the top level.
}

DELETE - /api/views/:viewid?deleteContent=true|false

Deletes a view. If deleteContent is true then all of the view's node positions and descendant views will also be deleted.

GET - /api/views/:viewid/childNodes/

Returns an unsorted array of all the child node IDs.

GET - /api/views/:viewid/childNodes/:nodeid

Returns the ID string if it is a child of the view or 404 if it is not.

PUT - /api/views/:viewid/childNodes/:nodeid

Adds the specified node to the specified view.

DELETE - /api/views/:viewid/childNodes/:nodeid

Deletes the specified node from the specified view.

GET - /api/views/:viewid/childViews/

Returns an unsorted array of all the child view IDs.

GET - /api/views/:viewid/remoteInterfaces/

Returns an array of all the remote interfaces assigned to the specified view.

iconSet values

The iconSet values possible on a default Mutiny install are:-

flat-largeFlat style64px
flat-smallFlat style32px
flat-tinyFlat style16px
rep-largeRepresentative style64px
rep-smallRepresentative style32px
rep-tinyRepresentative style16px
out-largeOutline style64px
out-smallOutline style32px
out-tinyOutline style16px
largeLegacy styleLarge
smallLegacy styleSmall
status-only-largeStatus Icon Only32px
status-onlyStatus Icon Only16px

Tasks

As adding and discovering nodes can take an extended period of time the API represents this by allowing tasks to be created that can be monitored by performing further requests.

GET - /api/tasks/

Returns the current and recent tasks as an unsorted array of objects. Superadmin users will see all tasks while other users will see the tasks they have created.

POST - /api/tasks/ - Discovery Task

Adds a new discovery task. The request body should contain a JSON document similar to:-

{
    "type": "discovery",                // Required
    "data": {
        "discoveryType": "pingOnly|allResponses|fullOnly|traceroute",    // Required
        "label": "Base Label",
        "addresses": ["x.x.x.1", "x.x.x.2", ...],
        "protoNodes": [
            { "address": "x.x.x.3", "label": "Node Label 1" },
            { "address": "x.x.x.4", "label": "Node Label 2" },
            ...
        ],
        "parentID": "Parent node of discovered nodes.",     // This parameter should normally be omitted for traceroute discovery.
        "allowDuplicates": true|false,      // Ignored for Traceroute discovery,
        "snmpVersion": "v1|v2c|v3",         // Ignored for Ping only discovery, automatic selection if omitted.
        "communityStrings": ["String 1", "String 2", ...],       // Used for V1/V2c SNMP discovery, default community strings are also included.
        "v3Credentials": [  // Used for V3 SNMP discovery, default V3 credentials are also included.
            {
                "user":"Username",
                "authPassword":"Authentication Password",
                "authProtocol":"MD5|SHA",       // Optional, defaults to SHA
                "privPassword":"Privacy Password",
                "privProtocol":"DES|AES",       // Optional, defaults to AES
                "sessionLength":"SHORT|MEDIUM|INDEFINITE"    // Optional, defaults to INDEFINITE
            },
            {
                ...
            },
            ...
        ]
        "rearrangeExisting":"OFF|ENDPOINTS_ONLY|ALL"     // Only used for Traceroute discovery, defaults to off. See below for details.
    }
}

Returns a Location header that represents the created task. The rearrangeExisting option should be used with care. It only considers the traceroute results when rearranging Nodes and does not account for switches or manual changes. There is also no automatic way of undoing the changes to the Node tree except for restoring a previous backup.

POST - /api/tasks/ - Update Task

Adds a new update task. The request body should contain a JSON document similar to:-

{
    "type": "update",                // Required
    "data": {
        "nodes": ["Node ID 1", "Node ID 2", ...],
        "action": "update|safe|new|recalc|custom",    // Optional, defaults to "update"
        "snmpVersion": "v1|v2c|v3",                   // Optional, automatic selection if omitted.
        "rediscoverWithDefaults": true|false          // Rediscover with default community strings, V3 credentials and port numbers,
                                                      // Optional, defaults to false if omitted or if action is "update"
    }
}

Returns a Location header that represents the created task.

POST - /api/tasks/ - Trace & Move Task

Adds a new Trace & Move task. This task takes a list of Node IDs, performs trace-routes to these Nodes, identifies the parent Nodes and moves them to the new parents. The request body should contain a JSON document similar to:-

{
    "type": "traceAndMove",                // Required
    "data": {
        "nodes": ["Node ID 1", "Node ID 2", ...],
        "rearrangeExistingParent": true|false       // Optional, when set to true a new parent Node will be picked if it is a better candidate even if
                                                    // the existing parent has the correct address. Defaults to false.
    }
}

Returns a Location header that represents the created task.

POST - /api/tasks/ - Test Node Task

Adds a new Test Node task. This task takes a single Node ID and a metric ID and performs the specified test. The request body should contain a JSON document similar to:-

{
    "type": "testNode",                // Required
    "data": {
        "node": "Node ID 1",
        "metric": "pingSimple|ping|snmp|snmpBroad|snmpV3|interfaces|cpu|memory|storage|processes|agents|qos|vpn"
    }
}

GET - /api/tasks/:taskid

Returns data about a single task as an object.

Users

GET - /api/users/

Returns data about all the Users that the API user is permitted to see as an array of objects.

GET - /api/users/:userid

Returns data about a single User as an object.

POST - /api/users/?autoCreateContact=...

Adds a new user. The request body should contain a JSON document similar to:-

{
    "emailAddress": "new.email@domain.com",           // Required
    "password": "...",                                // Required
    "name": "New Name",                               // Defaults to email address
    "notes": "...",
    "jobTitle": "...",
    "telephone1": "...",
    "telephone2": "...",
    "fax": "...",
    "enabled": true|false,                            // Defaults to true
    "allowedViews": ["viewID1", "viewID2", ...]       // Defaults to all views allowed.
    "roles": ["rolename1", "rolename2", ...]          // Defaults to "mut_access" and "mut_user"
                                                      // "mut_superadmin" is not permitted.
}

Returns a Location header that represents the created user. The API endpoint takes an optional parameter autoCreateContact. This can be set to:-

disabledA matching contact is not created. If omitted this is the default.
enabledA matching contact is created with the same name, email address, page number and views selected. Tracking of views is not enabled.
trackCriticalA matching contact is created with the same name, email address, page number and views selected. Tracking of view is enabled for critical events.
trackCriticalWarningA matching contact is created with the same name, email address, page number and views selected. Tracking of view is enabled for critical and warning events.

Locations

GET - /api/locations/

Returns data about all the Locations as an array of objects.

GET - /api/locations/:locationid

Returns data about a single Location as an object.

GET - /api/locations/:locationid/nodes/

Returns the Node IDs present at a single Location as an array of strings.

POST - /api/locations/

Adds a new Location. The request body should contain a JSON document similar to:-

{
    "name": "...",              // Required
    "dataCenter": true|false,   // Defaults to false
    "address1": "...",
    "address2": "...",
    "town": "...",
    "county": "...",
    "postcode": "...",
    "country": "...",           // 2 or 3 letter country code
    "notes": "...",
    "telephone1": "...",
    "telephone2": "...",
    "fax": "...",
    "postcode": "...",
    "latitude": ...number...,
    "longitude": ...number...
}

Returns a Location header that represents the created Location.

PUT - /api/locations/:locationid/nodes/:nodeid

Sets the Location of the given Node.

DELETE - /api/locations/:locationid/nodes/:nodeid

Removes the Location of the given Node.

Shared Data

Please note that the Shared Data API endpoints are only available on the Alma 8 platform.

GET - /api/sharedData/:collectionid/?time=...&startTime=...&endTime=...

Returns all the shared data documents for the given collection ID. The optional time parameter can be used to specify an exact time to look for document updates at. The time parameter should be used in conjunction with the format=timeline response. If the time parameter is not specified the optional startTime and endTime parameters can be used to specify a time range to look for document updates in. All the time parameters should be specified in ISO-8601 format. If the time range parameters are omitted the latest documents will be returned. The response will contain a JSON document similar :-

{
    "Document 1": {
        "cycleStartTime": "...",    // ISO-8601 timestamp
        "data": { ... }
    },
    "Document 2": {
        "cycleStartTime": "...",    // ISO-8601 timestamp
        "data": { ... }
    },
    "Document 3": {
        "cycleStartTime": "...",    // ISO-8601 timestamp
        "data": { ... }
    }
}

GET - /api/sharedData/:collectionid/:documentid?time=...&startTime=...&endTime=...&offset=...

Returns a shared data document for the given collection and document IDs. The optional time parameter can be used to specify an exact time to look for document updates at. The time parameter should be used in conjunction with the format=timeline response. If the time parameter is not specified the optional startTime and endTime parameters can be used to specify a time range to look for document updates in. The time parameters should be specified in ISO-8601 format. If a time range is not specified the optional offset parameter can be used to retrieve an old document and specifies the number of documents to skip. If the time range and offset parameters are omitted the latest document will be returned. The response will contain a JSON document similar :-

{
    "cycleStartTime": "...",    // ISO-8601 timestamp
    "data": { ... }
}

GET - /api/sharedData/:collectionid/?format=timeline

Returns a timeline of all the shared data document updates for the given collection ID. The response will contain a JSON document similar :-

{
    "Document 1": [
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "..."    // ISO-8601 timestamp
    ],
    "Document 2": [
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "..."    // ISO-8601 timestamp
    ],
    "Document 3": [
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "...",    // ISO-8601 timestamp
        "..."    // ISO-8601 timestamp
    ]
}

GET - /api/sharedData/:collectionid/:documentid?format=timeline

Returns a timeline of all the shared data document updates for the given collection and document IDs. The response will contain a JSON document similar :-

[
    "...",    // ISO-8601 timestamp
    "...",    // ISO-8601 timestamp
    "...",    // ISO-8601 timestamp
    "...",    // ISO-8601 timestamp
]

Predefined Agents

GET - /api/predefinedAgents/

Returns data about all the predefined Agents available on the system as an array of objects.

GET - /api/predefinedAgents/:agentid

Returns data about a single predefined Agent as an object.

System Configuration

Superadmin level permissions are required to access or modify any of the system configuration data.

GET - /api/systemConfig/frontend/publicData

Returns an object that describes the public data access configuration. This specifies whether the feature is enabled and, if it is enabled, the secret key and the creation time of the secret key.

POST - /api/systemConfig/frontend/publicData/generate

Generates the public data secret key. If the feature is disabled it is also enabled.

POST - /api/systemConfig/frontend/publicData/disable

Disable the public data access feature.