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

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

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

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

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.