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/:nodeid

Returns data about a single node as an object.

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/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 data for a single node as an object.

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/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. usageused_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 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 7 days 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.
calculateAggregatesWhether aggregate values should be calculated and returned. If set to true minimum, maximum and average values are calculated. The default is false.

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

{
    "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": "...",
            "warningThreshold": number,
            "criticalThreshold": 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
    }
}

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",
    "events": true|false,    // Enables and disables all events and 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.
        "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when turning maintenance mode on
    }
}

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.
    "endTime": "2019-09-17T17:30:00Z"   // UTC timestamp formatted according to ISO-8601. Required when turning maintenance mode on
}

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,
        "condition": {
            "ignoreConnectivity": true|false
        },
        "traffic": {
            "ignoreUsage": true|false,      // Defaults to false if omitted and thresholds are supplied.
            "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.

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.

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|fullSNMP|traceroute",    // Required
        "label": "Base Label",
        "addresses": ["IPv4 1", "IPv4 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",            // Ignored for Ping only discovery, automatic selection if omitted.
        "communityStrings": ["String 1", "String 2", ...],       // Ignored for Ping only discovery, default community strings are always included.
        "rearrangeExisting": true|false     // Only used for Traceroute discovery, defaults to false. 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"            // Optional, automatic selection if omitted.
    }
}

Returns a Location header that represents the created task.

GET - /api/tasks/:taskid

Returns data about a single task as an object.

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.

Feeds

GET - /feeds/openEvents/

Returns an RSS 2.0 feed that includes details about the open events on the Mutiny system. This feed can be used in a standard feed reader and it also includes extra <mut-evt:...> tags that provide more formatted details about the events. The <mut-evt:duration> tag is in milliseconds. Up to 100 open events are returned.

GET - /feeds/openEvents/:viewid

Returns an RSS 2.0 feed that includes details about the open events contained in a specified view. This feed can be used in a standard feed reader and it also includes extra <mut-evt:...> tags that provide more formatted details about the events. The <mut-evt:duration> tag is in milliseconds. Up to 100 open events are returned.