Use the Incidents API to retrieve incident data, merge incidents, or add comments to incidents in BigPanda
The Incidents API allows you to manage BigPanda incidents externally, and can be configured with external ticketing and monitoring tools. It provides the Incidents object, which represents a BigPanda incident containing correlated alerts from your integrated monitoring systems.
The Incident Search function uses BigPanda Query Language (BPQL) to filter the incidents in your BigPanda instance and return those that meet specific conditions. Set sort order, pagination rules, and query incidents by tag, time frame, source system, or more. The Incident Search function can be used to return all incidents in a specific environment.
Expanding Alert Data
To include the full alert object for each retrieved incident, include
expand=alertsin the query.When making a call with alerts expanded, page_size cannot be larger than 10. An expanded call with a page size greater than 10 will return a 400 error.
Incident Actions allows you to seamlessly manage incidents through the API. Incidents can be merged, split, assigned, snoozed, and commented on through the API.
A list of the actions that have been taken on an incident can be retrieved using the Get Activities function.
Environment ID
The environment ID can extracted from the URL of the BigPanda console in browser, or it can be retrieved through the Environments API
Environments with Incident Tags
Search functionality is currently unavailable for environments leveraging incident tags, and will return a 500 error.
If you are unsure which environments leverage incident tags, try searching the All Incidents environment.
Search functionality for environments with incident tags will be supported in the future.
Relevant Permissions
Incident permissions are defined by environment role access. To search incidents, you will need permission to view incidents in the specified environment. To merge or comment incidents, you will need incident action permissions in the specified environment.
| Name | Permissions |
|---|---|
Environments_Read | Retrieve an incident or retrieve all incidents from any environment |
Environments_Incident_Actions | Retrieve, comment, or merge incidents from any environment |
Environments_Full_Access | Retrieve, comment, or merge incidents from any environment |
\*\_Read | Granular - Retrieve an incident or retrieve all incidents from the specified environment |
\*\_Incident_Actions | Granular - Retrieve, comment, or merge incidents from the specified environment |
See the Incidents in BigPanda documentation or a full explanation of the permissions required to access the Incidents Settings section and the Incident Actions API.
To learn more about how BigPanda's permissions work, see the Roles Management guide.
Authentication Necessary
All BigPanda APIs require Bearer Token Authorization in the call headers.
This API uses the User API Key type of Authorization token.
Rate Limitations
To maintain quality of service, the Incidents API is limited to 10 requests per route, per second.
Additional requests will return a 429 response code and the request will need to be retried.
Available Objects & Actions
The Incidents API provides the following objects:
| Object | Description | Supported Methods | API Endpoint |
|---|---|---|---|
| Incident | Represents an incident in BigPanda | POST, GET | https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id} |
| Alert | Represents an alert that is contained in a BigPanda incident | GET | https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}?expand=alerts |
| Activities | Represents an action taken on a Bigpanda incident. Each type of Activity has a unique schema. | GET | https://api.bigpanda.io/resources/v2.0/incidents/{incident_id}/activities |
Use the Incidents API to perform these actions:
| Action | Definition | Description |
|---|---|---|
| Search Incidents | GET /environments/{environment_id}/incidents?{query} | Retrieves all BigPanda incidents that meet specific conditions |
| Retrieve Incident by ID | GET /environments/{environment_id}/incidents/{incident_id} | Retrieves a specific incident from a specific environment |
| Split Incident | POST /environments/{environment_id}/incidents/{incident_id}/split | Pulls alerts from an existing incident to create a new incident with only those alerts |
| Merge Incidents | POST /environments/{environment_id}/incidents/{incident_id}/merge | Merges a list of source incidents into a specific destination incident |
| Comment on Incident | POST /environments/{environment_id}/incidents/{incident_id}/comments | Adds a comment to a specific incident |
| Snooze Incident | PUT /environments/{environment_id}/incidents/{incident_id}/snooze | Adds the Snooze condition to an incident preventing share updates |
| Unsnooze Incident | DELETE /environments/{environment_id}/incidents/{incident_id}/snooze | Removes the Snooze condition from an incident, reenabling share updates |
| Assign Incident | PUT /environments/{environment_id}/incidents/{incident_id}/assignment | Adds an Assigned User to a specific incident |
| Unassign Incident | DELETE /environments/{environment_id}/incidents/{incident_id}/assignment | Removes the Assigned User from an incident |
| Resolve Incident | POST /environments/{environment_id}/incidents/{incident_id}/resolve | Resolves a BigPanda incident |
| Add Incident Tags | POST /environments/{environment_id}/incidents/{incident_id}/tags | Adds an array of Incident Tags to an incident |
| Add Incident Tag | POST /environments/{environment_id}/incidents/{incident_id}/tags/{tag_id} | Adds a specific singular Incident Tag to an incident |
| Get Activities | GET /incidents/{incident_id}/activities | Retrieves a list of actions taken on an incident |