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.

Example 1. Create a maintenance plan

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"
}'

Example 2. Retrieve a plan

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 '

Example 3. Retrieve all plans

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 '

Example 4. Update plan

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}
}'

Example 5. Stop plan

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 '

Example 6. Delete plan

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 `Once`. This field is case-insensitive.	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: `Resolve`, `Reactivate`, `None` Default is `None`	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