Skip to main content

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

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