For example:

"Authorization: Bearer ${token}" "Accept: application/json" "Content-Type: application/json; charset=utf8"

Authentication Tokens

Each organization has a unique bearer token for authenticating API requests. To access any API resource, every request must include this token as a value in the Authorization HTTP header.

To find your token in BigPanda, log in as an administrator and then click the Integrations tab at the top of screen. Open the instructions for the Alerts API. Your token appears in the example headers.

Content Types

Include the appropriate Content-Type and Accept headers to specify the representation of data sent to and retrieved from BigPanda. Most BigPanda APIs accept and respond with JSON content as the data payload. Refer to the API reference documentation for supported content types of each request.

This table lists some of the common response codes you may receive from the BigPanda API. Refer to the API reference documentation for specific response codes and errors, where applicable.

For example, append ?expand=alerts to the URI of an incident request to expand all the alert objects that the incident contains.

GET /incidents/{id}?expand=alerts

Objects that can be expanded are noted in the API reference documentation. Additionally, you can discover the identifiers for each expandable object by referencing the the expand property in the parent object. You can expand multiple objects at once by identifying multiple items in the expand array.

For example, uploading a mapping enrichment table. All asynchronous calls create a Job object and return the HTTP response code 202 Accepted and a location header. To obtain the actual result of the call, you have to check the job status by sending a GET request to the Job resource URL.

For example:

GET /enrichments/{id}/map/{job_id}

Key Features

• Enables custom integrations by sending high-level, correlated incidents from BigPanda to any Webhook receiver you configure.

• Sends incident data to an external URL via HTTP POST request.

• Supports custom authentication headers for data security.

• Supports AutoSharing, manual sharing, and sharing updates.

Webhooks Explained

In general, Webhooks are a programmatic way to send information to an Internet address when an event occurs in an application. In BigPanda, the Notifications Webhook allows you to send incident information to a callback URL when an incident is shared and when the shared incident is updated.

How It Works

A Notifications Webhook integration creates a sharing channel from BigPanda to a callback URL of your choosing. When an incident is shared via the channel, BigPanda sends an HTTP POST request to the callback URL. The data payload of the request is the Incident object with the expanded representation of the Alertobjects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for new shares from BigPanda. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to create a ticket for the team that handles incident escalations.

If a change occurs that triggers a sharing update for the incident, BigPanda sends another HTTP POST request to the callback URL, with the updated Incidentobject and Alert objects it contains. The application or service that receives the request can then process the data according to any business logic it has configured for updates to existing BigPanda shares. For example, if the callback URL is an API endpoint for a service desk application, you may configure the application to update the existing ticket for the shared incident.

You can use the Notifications webhook to build any number of custom collaboration integrations. As with other sharing channels, the same incident update can be shared through multiple webhook integrations.

Common Use Cases

The Notifications webhook is often used to integrate BigPanda with messaging, ticketing, or other collaboration systems. Some systems provide built-in API endpoints and scripting layers for receiving and transforming data according to custom business logic. Alternatively, you can build a custom API endpoint within your infrastructure or by using cloud services such as Amazon API Gateway and AWS Lambda.

Integrating Collaboration Systems With The Notifications Webhook

To build a custom integration with the Notifications webhook, you must configure the collaboration system to receive and use BigPanda incident data. Then, configure BigPanda to send the data.
Follow this general process to use the Notifications Webhook:

1. Configure The API Endpoint To Receive The Webhook.
   Be sure to configure security settings for authenticating requests, such as API keys or user account credentials. Consider configuring responses with status codes to aid in testing and troubleshooting.

2. Set Up The Receiving System To Use The Data.
   Apply custom business logic, transform the data, and/or perform actions in the system with custom code or settings. As necessary, configure data storage, include logic for receiving multiple requests about the same incident, and/or configure the API endpoint to trigger any custom code when data is received.

3. Configure The Webhook Settings In BigPanda.
   Create a sharing channel from BigPanda to the application or service. Provide the callback URL and authentication headers that BigPanda will use to send the incident data.

4. Test The Webhook.

5. Configure Environments And AutoShare Rules To Use The Webhook Sharing Channel, As Necessary.

BigPanda's APIs utilizes the BPQL object syntax when used for querying, which should not be confused with the string formatted BPQL when searching or filtering inside the UI itself.

The below BPQL object cheatsheets explain how a conventional BPQL string is represented as a JSON object instead. Again, use this format whenever a certain API requires filling in a bpql parameter, like Create a Plan.

Special Values

For commands with special values, the value will be represented inside an object. Here are two examples.

The Alerts API allows you to easily integrate a monitoring system with BigPanda. Monitoring systems generally send out events when problems are detected and when problems have been resolved (fixed).

The API works by receiving the events that your monitoring system sends. Incoming events sent via the REST API are processed according to the BigPanda alert correlation logic. Depending on the results of the correlation, the system then creates a new incident or updates an existing incident.

If the tool you are integrating with does not support HTTP headers, you can use the access_token URL parameter for authentication. For example:

https://api.bigpanda.io/data/v2/alerts?access_token=<YOUR TOKEN>

Available Methods

Custom Wrappers

BigPanda provides the following wrappers for calling the Alerts API from custom scripts:

• Bash Shell utility
• Python module

Prerequisites

• Obtain administrator access to BigPanda
• Determine how your monitoring system triggers API calls—webhooks or custom script calls.

Using a Webhook to Integrate a Monitoring System

If the monitoring system supports custom HTTP callbacks, you can follow this general process to integrate it with BigPanda:

1. In BigPanda, create an App Key.
   Each integration must have an App Key in BigPanda to identify it as a unique source.
2. In your monitoring system, configure the webhook to send alerts to BigPanda.
3. Test the integration by sending a test alert.

Using a Custom Script to Integrate a Monitoring System

If the monitoring system does not support webhooks, you can write a custom script. Follow this general process to integrate it with BigPanda:

1. In BigPanda, create an App Key.
   Each integration must have an App Key in BigPanda to identify it as a unique source.
2. Download one of the BigPanda-provided wrappers or use a custom wrapper.
   You must install the wrapper on a server that has access to the monitoring data.
   The server must be able to run the code. For example, to use the BigPanda Python module, Python must be installed and running on the server.
3. Write a custom script to send alerts to BigPanda via the Alerts API.
4. Configure your monitoring system to call your custom script.
5. Test the integration by sending a test alert.

When to Send Events

• Send an event every time the status of an alert changes.
  For example, a new Critical alert is opened or a Critical alert becomes a Warning. The status of an alert typically changes when a metric goes above or below a certain threshold.
• Send an OK resolution event when an alert is no longer active.
  BigPanda does not resolve alerts automatically. Alerts that have not been resolved remain open, and the corresponding incident also remains open and continues to appear in the incident feed.

• Send an updated event when you need to change tag values for an alert.
  In some rare cases, you may want to send an event for an alert with the same status but a different value for one or more tags. For example, assume you have an alert with status of Warning and description of problem1. You can send a new Warning event with a description of problem2, and the alert status remains the same but the description is updated.

What Tags to Send

The attributes in your JSON payload become tags that you can use in BigPanda. When defining an integration with the Alerts API, send tags that:

• Provide users with information about where the alert was triggered.
  It is common to include information such as the host or virtual node. Consider including additional information, such as cluster, data center, and server role, which can be very useful when investigating a problem.
• Support the teams and processes in your organization.
  Consider how you plan to use tag values to define your Environments, AutoShare rules, and Analytics reports. For example, consider the teams' areas of responsibility, processes, or escalation paths.
• Include links for additional information about the alert.
  For example, send a link to documentation (such as a runbook wiki) or investigation tools (such as a metrics dashboard). If one of the tag values starts with http, BigPanda automatically adds a link button for that alert.

How Many Events to Send (Load Limitations)

• If an integration generates more than a few hundred event per hour, review the guidelines for when to send events and ensure that the integration is properly configured.
  Even with hundreds of thousands of monitoring metrics, status changes do not happen very often. If an integration exceeds this guideline, it may be sending duplicate or erroneous events to BigPanda.
• Under maximum load, the API can support up to few hundred events per minute.
  If you think you need support for more than this limit, please contact BigPanda support to discuss your use case.

Parameters (Multiple Alerts)

If you want to send more than one alert in a single API call, you can modify the JSON payload to contain these main properties.

Parameters (Primary and Secondary Properties)

BigPanda treats certain properties as primary and secondary by default. In some cases, you may want to control which properties are treated as primary or secondary. For example, you may have an alert that is associated with both a host and an application, where the application is primary and the host is secondary. In these cases, use the primary_property and secondary_property properties.

The Incidents API allows you to build integrated functionality between an external ticketing or collaboration system and BigPanda. It provides the Incidents object, which represents a BigPanda incident containing correlated alerts from your integrated monitoring systems.

Use the Incidents API to retrieve, snooze, or resolve an incident in BigPanda.

Available Objects & Actions

The Incidents API provides these objects.

Use the Incidents API to perform these actions.

Parameters

The Incidents object schema includes the following attributes.

Parameters

The Alerts object schema includes the following attributes.

The Enrichments API allows you to programmatically create custom tags that add contextual information to alerts. It supports the mapping enrichment technique, which creates custom tags by looking up values in a data mapping table.

You define an enrichment schema by using these API resources:

• Enrichments object, which defines the enrichment technique and configuration details associated with that technique. For example, in a mapping enrichment, the configuration details include a description of the data mapping table.
• Sub-objects that are specific to the enrichment technique. For a mapping enrichment, the Map endpoint allows you to upload and maintain a data mapping table.

The API works by evaluating all incoming alerts to see if they match an active enrichment definition. Matching alerts are enriched with custom tags according to the instructions in the enrichment definition.

Use Cases

You can use the Enrichment API to develop a common language between monitoring systems and to identify upstream and downstream dependencies between configuration items.

Cross-Source Relationships

Define common tags to identify when alerts from different monitoring sources are related to the same monitored object in your infrastructure. For example, you can define a mapping enrichment for cluster based on the Pingdom service. Then, define an extraction enrichment for cluster based on the Nagios host name. Now, a cross-source correlation pattern on the cluster tag can group related alerts from either system into the same incident.

Topology Metadata

Understand the physical and logical relationships between alerting objects and the rest of your infrastructure. For example, you can leverage a CMDB to identify when different objects have the same parent object (such as multiple hosts in the same cluster). Then, define correlation patterns for objects with the same parent, Environments that reflect your infrastructure, and/or maintenance plans that suppress alerts for objects downstream of an object under maintenance.

Operational Metadata

Help IT Operations teams categorize, prioritize, route, and remediate an incident. For example, you can leverage a team spreadsheet to add assignments, categories, and priorities to alerts. Then, define Environments, dashboards, and Analytics reports to ensure the right teams have visibility into issues and/or define AutoShare rules to automatically trigger escalation processes.

Available Objects & Actions

Use the Enrichments API to perform these actions.

The mapping enrichment technique creates custom tags by looking up values in a data mapping table. You define a mapping enrichment with the Enrichments API by using these resources:

Mapping Enrichment Overview

• Enrichments object—defines the schema for your data mapping table. The schema determines how the information in each column of the table will be used in the enrichment process—as a query field, to match a value in the incoming alert, or as a result field, to enrich the alert.

• Map endpoint—allows you to upload and maintain a data mapping table that follows a given Enrichments schema.

The API works by evaluating all incoming alerts to see if they match an active mapping enrichment. When an alert matches the values in the query fields, it is enriched with the values in the result fields.

Prerequisites

• Obtain the BigPanda token for your organization.
  Administrators can find the token by clicking the Integrations tab, and then opening the instructions for the Alerts API

• Obtain the mapping data that you want to leverage (such as a CMDB, registry, or team spreadsheet).

• (Recommended) Review the overview of enrichment.

Step 1: Define The Mapping Structure

For a mapping enrichment, the Enrichments object defines how the information in each column of the table will be used in the enrichment process:

Query field—to match a value in the incoming alert.

Result field—to enrich the alert.

For example, suppose that certain applications have an owner on the operations team and a standard runbook for remediating common problems. You would create an enrichment schema that maps the application names (query field) to their owners and runbook URLs (result fields).

To define the mapping structure for a new enrichment:

1. Send a POST request to /enrichments.

   • Specify the type as mapping.

2. For each column in your data table, specify the name and whether to use the values as a query_tag or a result_tag.

3. For more information, see Create Enrichment.

4. The request creates a new Enrichments object for this mapping enrichment schema.

2. Copy the id value from the response body. You will use it to identify this schema when you upload and update the mapping data.

Step 2: Upload The Mapping Data

After you create an Enrichments object that defines its structure, you can upload the table of the mapping data. For example, suppose that the Billing and Sales applications both have owners and remediation procedures. You can upload a table with three rows—one row for the column names and one row for each application.

To upload the mapping data for an enrichment:

1. Send a POST request to /enrichments/${id}/map.

2. Send the mapping data as comma-separated values (CSV) in the body of the request or in a CSV file.

3. Ensure the data follows the structure you defined in Step 1 and has the same column names.

4. For more information, see Create Mapping Enrichment Table.

5. The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

2. Copy the trigger_uri value from the response body.
   You will use it to check the status of the upload.

3. Send a GET request to the ${trigger_uri} to verify that the upload has completed successfully.
   For more information, see Check Status of Upload Job.

4. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.
   For example, you can run the following command to send matching test alerts via the Alert API. For more information, see POST alerts.

5. Resolve any test alerts, as necessary.

Step 3. Maintain the Mapping Data

As your team and infrastructure changes, you may need to update the values for your mapping enrichment. For example, suppose the Accounts application has just come online, the Payroll application has a new owner, and the Sales application is no longer being used. Depending on what changes you want to make, you can either completely replace the existing table, change only specific rows in the table, or create a new enrichment to change the structure.

To completely replace the existing table but keep the same structure, repeat Step 2. Upload the Mapping Data, above.

To change only specific rows in the existing table:

1. Send a PATCH request to/enrichments/${id}/map.

   • For each row, specify the operation to perform (create, update, delete, upsert) and the data required to perform the operation.

   • For more information, see Update Mapping Enrichment Table Rows.

   • The request initiates an asynchronous job to upload the table and creates a Job object to track its progress.

2. Copy the trigger_uri value from the response body.
   You will use it to check the status of the update.

3. Send a GET request to the ${trigger_uri} to verify that the update has completed successfully.
   For more information, see Check Status of Upload Job.

4. (Recommended) Send test alerts to ensure that the mapping enrichment works as expected.

5. Resolve any test alerts, as necessary.

To change the structure of your mapping data:

1. Deactivate the existing enrichment by sending a POST request to /enrichments/${id}.
   Set active to false.
   For more information, see Update Enrichment.

2. Create a new mapping enrichment, starting from Step 1: Define The Mapping Structure, above.

Post-Requisites

• Continue to maintain the mapping data as team assignments change.

• (Optional) Define Environments based on the custom tags.

• (Optional) Define additional mapping enrichments.

Parameters

The Enrichments object includes the following attributes.

Map Configuration Fields

The following attributes describe how to enrich alerts based on a given data mapping table.

`

Returns

Possible response codes include:

• 201 Created—new schema definition was created successfully.
• 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.

Returns

Enrichments object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

• 200 OK
• 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all enrichments to find the correct enrichment id.

Usage

The Enrichments API supports updating only the active attribute of an existing enrichment. If the structure of your mapping enrichment tables changes and you need to update the schema definition, you must deactivate the existing enrichment and create a new enrichment for the updated schema definition.

Returns

Response code indicating whether the enrichment was updated successfully. Possible response codes include:

• 200 OK—the enrichment was updated successfully.
• 400 Bad Request—the enrichment was not updated because the request was not properly formatted. The response body includes additional error information for debugging.

Returns

Status of deletion with a job_id of the asynchronous task.

• 200 OK

Returns

Array of Enrichments objects for the organization. Possible response codes include:

• 200 OK—returns the array of all matching enrichments.
• 204 No Content—no enrichments match the request.
• 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.

Usage

Use this action to create a new table for a mapping enrichment or to completely replace the existing table. Send the entire table as comma-separated values (CSV) in the body of the request or in a CSV file. The data table must meet these requirements:

• The structure matches the mapping schema definition. For example, the column names must match the titles in the schema definition. Similarly, the table must include all of the columns in the definition.
• The table contains at least two rows—the title row and at least one row of enrichment values.
• Each row is unique; the table must not contain duplicate rows.
• The field values do not exceed 32K in length.

Because it is a potentially long-running action, the table upload is performed asynchronously. Therefore, the immediate response indicates only whether the request was properly formatted and, if it was, provides a URL for checking the status of the upload. The entire table upload must complete successfully for the changes to take effect; the API does not support partial success.

A typical asynchronous upload negotiation consists of these steps:

1. Upload the table.
   A Job object is created and a URL for checking the status is returned.
2. Use the URL to periodically check the job status until it is set to done or failed.
3. If the job was not successful, you can retry the request.
   If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Returns

If the request is valid, the Job object for the table upload and the following header:

Possible response codes include:

• 202 Accepted—the table upload is in progress.
• 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.

Usage

Use this action to update specific rows in an existing mapping enrichment table. To completely replace the existing table, see Create Mapping Enrichment Table. For each row, send the operation to perform and the values required to perform the operation. You can send up to 100 operations per request. The API supports these operations:

• create—adds a new row in the table. Requires values for every column in the row. If the row already exists, this operation will fail.
• update—updates an existing row in the table. Requires values for every column in the row.
• delete—removes an existing row from the table. Requires values for the query fields only. If the row does not exist, this operation will succeed but the version count will not be incremented.
• upsert—adds a new row, if the row doesn't exist, or updates the row, if it already exists. Requires values for every column in the row.

Because it is a potentially long-running action, the table update is performed asynchronously. Therefore, the immediate response indicates only whether the request was properly formatted and, if it was, provides a URL for checking the status of the upload. The entire table update must complete successfully for the changes to take effect; the API does not support partial success.

A typical asynchronous upload negotiation consists of these steps:

1. Send the update request.
   A Job object is created and a URL for checking the status is returned.
2. Use the URL to periodically check the job status until it is set to done or failed.
3. If the job was not successful, you can retry the request.
   If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Returns

Possible response codes include:

• 202 Accepted—the table update is in progress.
• 400 Bad Request—the request was not properly formatted or the number of requested operations exceeds 100. The response body includes additional error information for debugging.

Usage

Use this action to retrieve a specific mapping enrichment table. This only applies to Mapping Enrichments and not for standard Enrichments.

The result yields a total_count field that represents the total number of mapping entries and the list of items in the table.

Optional pagination parameters may be included to refine the results further. If used, these parameters are to be formatted at the end of the link:

GET /enrichments/{ID}/map?page&per_page

Returns

Possible response codes include:

• 200 OK—the table exists in the response.
• 404 Not Found—the table was not found. Also occurs when a non-mapping enrichment is attempted for retrieval.

Usage

Jobs are objects that manage asynchronous tasks for potentially long-running actions, such as uploading or updating a mapping enrichment table. When these actions are performed, a new job is created, and the API returns the Job object and a location header with the URL for checking the status.

When performing actions that use jobs, follow these steps:

1. Make a request (for example, upload a mapping enrichment table).
   The associated Job object is created and a URL for checking the status is returned.
2. Use the URL to periodically check the job status until it is set to done or failed.
3. If the job was not successful, you can retry the request.
   If necessary, debug any connectivity issues or data formatting issues that may have contributed to the failed upload. For example, ensure the CSV file follows the enrichment schema definition.

Returns

Possible response codes include:

• 200 OK—the job is complete. The status attribute in the response body indicates whether the job was successful.
• 202 Accepted—the job is in progress.

The Maintenance Plan API supports two new resources to control the maintenance windows: plans (required) and schedules (optional).

Plans are configured with BPQL queries and, once activated, will filter/suppress events that matches the criteria. Origin tags supplied by a monitoring source and automatically generated enriched tags by the Enrichment API are also supported for querying. User created tags from the Custom Tags Editor are not supported.

Schedules define a start and stop time frame which can be applied to a Plan. Once a Schedule is deactivated, the Plan will cease to continue filtering. If a Plan does not have a Schedule defined, it will start immediately and run indefinitely - until an administrator manually deletes the plan or updates it to inactive.

Use Cases

You can use the Maintenance Plan API to keep in sync with infrastructure changes and parallel your monitoring activity accordingly. For example, the set of servers under a certain host, i.e. Billing, is scheduled to undergo upgrades for a duration of one week. Due to the non-operational nature of the servers during this time, all alerts generated by them will be unnecessary for monitoring.
Instead of having these alerts continue to stream into the feed and disrupt workflow, create a matching Plan with the query host = "billing*" and a Schedule of one week in the same time frame as the upgrades. This will suppress the irrelevant alerts from ever entering the feed.

Available Objects & Actions

Use the Plans API to perform these actions:

Actions

Create Plan — Creates a new schema definition for creating a plan.

Create Schedule — Creates a new schema definition for creating a schedule.

Create Plan with Schedule and Custom Tags — Creates a new schema definition for creating a plan with schedule and custom tags.

Retrieve Plan — Retrieves a specific schema definition for a created plan.

Update Plans — Updates a specific plan to stop maintenance period immediately.

List All Plans — Lists all plan schema definitions that exist for an organization.

Delete Plan — Lists all plan schema definitions that exist for an organization.

Prerequisites

Step 1: Define The Schedule

As an example scenario, suppose that a company's servers and devices under its San Jose host are undergoing upgrades and will yield false alerts from procedural reboots and state changes. The associated monitoring tools will inevitably see these changes as alerts and stream them into BigPanda. To prevent the cluttering of workflow, you would create a plan to capture the relevant devices under the San Jose host and suppress their alerts and a schedule to capture the timeframe of the maintenance period.

Start by creating a schedule to define the specific start and end timeframe:

1. Send a POST request to /schedules.

2. The start and end parameters follow the Unix epoch format.

3. For more information, see Create a Schedule

2. Copy the id value from the response body.
   You will use it as a parameter when creating a plan in the next step.

Step 2: Define The Plan With Schedule

Create a plan to isolate the suppression of alerts to only the devices affected during the maintenance period - the San Jose host. See the Plans Object page for more information on the Plan Objects

To define a new plan:

1. Send a POST request to /plans.

   • Specify the name of the plan.

   • Specify the schedule to associate with the plan. The id value is copied from Step 1.

2. Specify the bpql object to query. In this case, we want to filter "San Jose" hosts to capture the relevant devices.

   • Specify the active parameter to true to enable the plan.

   • For more information, see Create a Plan

2. (Recommended) Send test alerts from the San Jose host and ensure that they are suppressed and the plan works as expected.

Post-Requisites

• Continue to maintain the plan and schedule as the infrastructure upgrade dictates.

• (Optional) Create A Plan With Custom Tags.

Parameters

The Plan object schema includes the following attributes.

Returns

Possible response codes include:

• 201 Created—new schema definition was created successfully.
• 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.

Returns

Plans object for the specified enrichment if a valid identifier was provided. Possible response codes include:

• 200 OK
• 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.

Usage

The Plans API supports retrieval of all active plans or all plans. The desired output is obtained by appending ?active=true to the GET definition. Omitting this will yield all plans, both active and inactive.

Returns

Plans object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

• 200 OK
• 400 Bad Request—the request was not properly formatted. The response body includes additional error information for debugging.

Returns

Response code indicating whether the plan was updated successfully. Possible response codes include:

• 204 No Content—the plan was updated successfully.
• 400 Bad Request—the plan was not updated because the request was not properly formatted. The response body includes additional error information for debugging.
• 404 Not Found—the plan failed to update because the plan ID provided could not be found.

Returns

Response code indicating whether the enrichment was updated successfully. Possible response codes include:

• 204 No Content—the plan was deleted successfully.
• 404 Not Found—the plan failed to delete because the plan ID provided could not be found.

The required Plans resource of the Maintenance Plan API can be augmented with the optional Schedules resource. Defining Schedules will allow for control of when a Maintenance Plan should start and stop. Otherwise, a Maintenance Plan will run indefinitely unless manually deleted or set to inactive by an administrator.

Please see the Plans API for more holistic information around the Use Cases and Actions.

Parameters

The Schedules object schema includes the following attributes.

Returns

A summarization detail with additional schedule objects, where applicable.

Possible response codes include:

• 201 Created—new schema definition was created successfully.
• 400 Bad Request—schema definition was not created because the request was missing parameters or not properly formatted. The response body includes additional error information for debugging.

Returns

Schedules object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

• 200 OK
• 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.

Returns

Schedules object for the specified enrichment, if a valid identifier was provided. Possible response codes include:

• 200 OK
• 404 Not Found—the specified enrichment id does not exist or the request URL is incorrect. You can list all plans to find the correct enrichment id.

Returns

Response code indicating whether the plan was updated successfully. Possible response codes include:

• 204 No Content—the plan was updated successfully.
• 400 Bad Request—the plan was not updated because the request was not properly formatted. The response body includes additional error information for debugging.
• 404 Not Found—the plan failed to update because the plan ID provided could not be found.

Returns

A summarization detail with additional schedule objects, where applicable.

Possible response codes include:

• 204 No Content—the schedule was deleted successfully.
• 404 Not Found—the schedule failed to delete because the schedule ID provided could not be found.

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. Origin tags supplied by a monitoring source and automatically generated enriched tags by the Enrichment API are also supported for querying.

Maintenance plans have three status modes:

• Plan - Plans with Plan status can be planned, duplicated or deleted.
• In Progress - An In Progress plan can be duplicated, extended or stopped.
  • When a plan is stopped, its End time is automatically updated to the time it was stopped.
  • In Progress plans cannot be edited or deleted.
• Done - A Done plan can be deleted and/or duplicated but cannot be edited.

Available Objects & Actions

To learn more about Maintenance Plans v2, see Maintenance Plans V2 (Beta).

Parameters

The Maintenance Plan object schema includes the following attributes:

Returns

Possible response codes include:

• 201 Created—Created. Return document.

Returns

Possible response codes include:

• 200 OK—Results are returned.
• 404 Not Found—The specified plan ID does not exist or the request URL is incorrect.

Returns

Possible response codes include:

• 200 OK—Results are returned.
• 404 Not Found—No plans exist or the request URL is incorrect.

If there are more than the default 100 plans retrieved, a link header to access the next page of results will be returned:
</maintenance-plans?pagination=true&next=2_1564317563_5d3d977b310000179e99ecdd>; rel=next