maintenance.create

Description

object maintenance.create(object/array maintenances)

This method allows you to create new maintenances.

This method is only available to Admin and Super admin user types. Permissions to call the method can be revoked in user role settings. See User roles for more information.

Parameters

(object/array) Maintenances to create.

Additionally to the standard maintenance properties, the method accepts the following parameters.

Parameter Type Description
groups object/array Host groups to be put into maintenance.

The host groups must have only the groupid property defined.

Parameter behavior:
- required if hosts is not set
hosts object/array Hosts to be put into maintenance.

The hosts must have only the hostid property defined.

Parameter behavior:
- required if groups is not set
triggers object/array Triggers to be put into maintenance.

The triggers must have only the triggerid property defined.

Parameter behavior:
- required if groups and hosts are not set
- supported if maintenance_type=0 (with data collection)
event_names object/array Event names to define problems to be put into by maintenance.

Parameter behavior:
- supported if maintenance_type=0 (with data collection)
tags object/array Problem tags to define problems to be put into maintenance.

Parameter behavior:
- supported if maintenance_type of Maintenance object is set to "with data collection"
timeperiods object/array Maintenance time periods.

Parameter behavior:
- required

Return values

(object) Returns an object containing the IDs of the created maintenances under the maintenanceids property. The order of the returned IDs matches the order of the passed maintenances.

Examples

Creating a maintenance

Create a maintenance with data collection for host group with ID "20", and with problem tags service:mysqld and error. It must be active from 17.03.2026 till 17.03.2027, come in effect each Sunday at 18:00 and last for one hour.

Request:

{
    "jsonrpc": "2.0",
    "method": "maintenance.create",
    "params": {
        "name": "Sunday maintenance",
        "active_since": 1773720240,
        "active_till": 1805256240,
        "tags_evaltype": 0,
        "groups": [
            {"groupid": "20"}
        ],
        "timeperiods": [
            {
                "period": 3600,
                "timeperiod_type": 3,
                "start_time": 64800,
                "every": 1,
                "dayofweek": 64
            }
        ],
        "tags": [
            {
                "tag": "service",
                "operator": "0",
                "value": "mysqld"
            },
            {
                "tag": "error",
                "operator": "2",
                "value": ""
            }
        ]
    },
    "id": 1
}

Response:

{
    "jsonrpc": "2.0",
    "result": {
        "maintenanceids": [
            "3"
        ]
    },
    "id": 1
}

Creating ad-hoc maintenance

Create a one hour ad-hoc maintenance with data collection for host group with ID "4", trigger with ID "12345", and event name Printer: ink low.

Request:

{
    "jsonrpc": "2.0",
    "method": "maintenance.create",
    "params": {
        "name": "Ad-hoc maintenance",
        "active_since": 1792057740,
        "active_till": 1792061340,
        "tags_evaltype": 0,
        "groups": [
            {"groupid": "4"}
        ],
        "triggers": [
            {"triggerid": "12345"}
        ],
        "timeperiods": [
            {
                "period": 3600,
                "timeperiod_type": 0,
                "start_date": 1792057740
            }
        ],
        "event_names": [
            {
                "operator": "2",
                "value": "Printer: ink low"
            }
        ]
    },
    "id": 1
}

Response:

{
    "jsonrpc": "2.0",
    "result": {
        "maintenanceids": [
            "4"
        ]
    },
    "id": 1
}

See also

Source

CMaintenance::create() in ui/include/classes/api/services/CMaintenance.php.