Maintenance Plans V2
Use the Maintenance Plans API to define time windows that parallel infrastructure changes of respective monitored services.
Maintenance Plans are configured in BPQL Object format and, once activated, mark events that match the criteria for maintenance. Alert tags are also supported for querying.
Maintenance Plans
Authentication
All BigPanda APIs require Bearer Token Authorization in the call headers.
This API uses the User API Key type of Authorization token.
BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls.
Plan limit
Each organization can only have 3,500 maintenance plans at a time.
Condition limitations
Maintenance plan conditions cannot be longer than 25,000 characters long.
All alert tags in maintenance plan conditions are case-insensitive.
Relativity required for all update calls
Relativity must be included on all update calls for Maintenance plans with relative time defined.
curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ https://api.bigpanda.io/resources/v2.0/maintenance-plans \ -d '{ "name": "host1 maintenance", "condition": {"=": ["host", "prod-api-1"]}, "start": 1733904622, "end": 1734768622, "time_zone": "UTC", "description": "this is a description", "custom_tags": [ { "name" : "app", "value" : "esp"} ], "frequency": "Daily", "frequency_data": { "relativity": "First", "duration": 10800}, "post_maintenance_action": "None" }'
curl -X POST -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans \ -d '{ "name": "host1 maintenance", "condition": {"=": ["host", "prod-api-1"]}, "start": 1733904622, "end": 1734768622, "time_zone": "UTC", "description": "this is a description", "custom_tags": [ { "name" : "app", "value" : "esp"} ], "frequency": "Daily", "frequency_data": { "relativity": "First", "duration": 10800}, "post_maintenance_action": "None" }'
curl --request GET \ --url https://api.bigpanda.io/resources/v2.0/maintenance-plans/${id} \ --header 'Content-Type: application/merge-patch+json; charset=utf-8' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl --request GET \ --url https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans/${id} \ --header 'Content-Type: application/merge-patch+json; charset=utf-8' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl --request GET \ --url https://api.bigpanda.io/resources/v2.0/maintenance-plans \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl --request GET \ --url https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ https://api.bigpanda.io/resources/v2.0/maintenance-plans \ -d '{ "name": "host1 maintenance", "condition": {"=": ["host", "prod-api-1"]}, "start": 1733904622, "end": 1734768622, "time_zone": "UTC", "description": "this is a description", "custom_tags": [ { "name" : "app", "value" : "esp"} ], "frequency": "Daily", "frequency_data": { "relativity": "First", "duration": 10800} }'
curl -X PATCH -H 'Content-Type: application/json' \ -H 'Authorization: Bearer ' \ https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans \ -d '{ "name": "host1 maintenance", "condition": {"=": ["host", "prod-api-1"]}, "start": 1733904622, "end": 1734768622, "time_zone": "UTC", "description": "this is a description", "custom_tags": [ { "name" : "app", "value" : "esp"} ], "frequency": "Daily", "frequency_data": { "relativity": "First", "duration": 10800} }'
curl --request POST \ --url https://api.bigpanda.io/resources/v2.0/maintenance-plans/${id}/stop \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl --request POST \ --url https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans/${id}/stop \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer '
curl --request DELETE \ --url https://api.bigpanda.io/resources/v2.0/maintenance-plans/${id} \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Authorization: Bearer '
curl --request DELETE \ --url https://eu-api.bigpanda.io/resources/v2.0/maintenance-plans/${id} \ --header 'Content-Type: application/json; charset=utf-8' \ --header 'Authorization: Bearer '
Parameters
The Maintenance Plans
object schema includes the following attributes:
Attribute | Description | Type |
---|---|---|
id | System-generated unique identifier for a maintenance plan. | String |
status | The maintenance plan's status. | String |
maintenance_key | Third party (Jira, ServiceNow, etc.) system key for integrated maintenance management. If no integration key is included in the call, a system ID will be added automatically. | String |
name | User-defined name for the plan. | String |
start | Unix epoch time when the scheduled plan starts (in seconds). For recurring plans, this time should be the start of the first maintenance window. | String |
end | Unix epoch time when the scheduled plan ends (in seconds). For recurring plans, this time should be the date when the plan should stop repeating. | String |
time_zone | The maintenance plan's time zone setting. Default is UTC. See the full list of supported time zones here. | String |
condition | Maintenance condition in BPQL Object format. Cannot be longer than 80,000 characters. | String |
frequency | How often the scheduled plan should silence alerts. One of: - Once - Daily - Weekly - Monthly Default is | String |
frequency_data | For recurring plans only. Defines the plan window when alerts should be silenced each period. See the Frequency Data Object table for detailed attributes. | Object |
description | Brief user-defined summary of the maintenance plan. | String |
custom_tags | Metadata about the plan in an array of key:value pairs. Attributes: name - name of the tag value - value of the tag | Array of Objects |
created_at | System Field Unix epoch time when the plan was created (in seconds). | Integer |
created_by | System Field The ID of the user who created the plan. | String |
updated_at | System Field Unix epoch time when the plan was last updated (in seconds). | Integer |
updated_by | System Field The ID of the user who last updated the plan. | String |
post_maintenance_action | What should happen to alerts suppressed by this plan after the maintenance window ends. One of: Default is | String |
Epoch Converter
See the Epoch Converter to convert times to unix epoch format.
Retrieval limits
Maintenance plans can only be returned for 60 days after the end date.
The API can only return up to 100,000 maintenance plans
Update limitations
In planned plans, any field can be updated.
In running plans, only the plan's end field can be updated.
Condition limitations
Maintenance plan conditions cannot be longer than 25,000 characters long.
All alert tags in maintenance plan conditions are case-insensitive.
Frequency Data Object Parameters
The frequency_data
object schema includes the following attributes:
Attribute | Description | Type |
---|---|---|
relativity | Required for plans using relative monthly dates. What week in the month the window should take place. One of: - First - Second - Third - Fourth - Last Last will trigger in the 5th week for months with a 5th week, and otherwise default to the 4th. | String |
duration | Required for all recurring plans. The length of time the plan should run in milliseconds. | Integer |
current_run | System-generated field. Unix epoch time when the current running maintenance window began (in seconds). | String |
next_run | System-generated field. Unix epoch time when the next scheduled maintenance window starts (in seconds). | String |
Relativity required in all update calls
Relativity must be included on all update calls for Maintenance plans with relative time defined.
Sample Maintenance Object
{ "id": "64f0d836310000a6bc72fa7a", "status": "in progress", "maintenance_key": "MNT-a9b9030cbda7", "name": "host3 maintenance", "condition": { "=": [ "host", "prod-api-1" ] }, "start": 1718029999, "end": 1818029999, "time_zone": "UTC", "description": "this is a description", "selected_source_system": null, "custom_tags": [ { "name": "App", "value": "esp" } ], "created_by": "63bd568977a8d60012bf3dbe", "created_at": 1693505590, "updated_by": "63bd568977a8d60012bf3dbe", "updated_at": 1718029640, "frequency": "Daily", "frequency_data": { "duration": 10800000, "current_run": 1720017199, "next_run": 1720103599, "relativity": "First" }, "post_maintenance_action": "None" }