Incidents API V2

Use the Incidents API to retrieve incident data, merge incidents, or add comments to incidents in BigPanda.

👍

Our Incidents API V2 is now in GA! Find the official current API here!

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.

Incident Actions allows you to seamlessly manage incidents through the API. Incidents can be merged, and commented on through the API.

👍

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

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.

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 Working with Incidents 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 RBAC - Role Based Access Control guide.

📘

Authentication Necessary

A User API Key is required for authentication.

🚧

Rate Limitations

To maintain quality of service, BigPanda APIs are limited to 5 requests 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

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

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

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

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

Incident Object

Defines the schema for an incident in BigPanda.

Parameters

The Incident object schema includes the following attributes:

Parameter

Description

Type

Example

id

System-generated unique identifier for the incident.

String

"id": "1234a53b6789c12d3efg45h"

status

Current incident status, which is determined by the most severe status of the correlated alerts. Possible statuses: [critical, warning, unknown, ok].

String

"status" : "critical"

active

Whether the incident contains at least one active alert and has not been manually resolved. An incident is automatically resolved when all the alerts are resolved.

Boolean

"active": true

severity

The highest status the incident reached

String

“severity”: “critical”

flapping

Whether at least one correlated alert has changed states frequently enough to be treated as flapping

Boolean

"flapping": false

shared

Whether the incident has been shared

Boolean

"shared": false

snooze

Snooze options for the incident
Attributes:
snoozed - Whether the incident is currently snoozed.
end_time - Time when the current snooze period expires, in Unix epochs.
cancel_on_incident_updates - Whether the current snooze should be automatically cancelled if a new alert is added, the severity of an existing alert increases, or the incident is resolved and then reopens.

Object

"snooze" : {"snoozed" : false, "end_time" : null, "cancel_on_incident_updates" : false}

maintenance

Whether an incident is in maintenance
null - not in maintenance
partial - one of the alerts is in maintenance
active - all alerts in maintenance

String

“maintenance”: “partial”

correlation_matchers_log

Log of the correlation patterns matched to the incident over time.

The last item in the array is the most recent one.

Array

“Correlation_matchers_log”: [ {
"time_window": 60,
"tags": [{"name": "cluster", "value": "api"}, {"name": "category", "value": "load" } ],
"correlation_id": "a02fde2f-0ec3-4cc2-9cbd-74823cb11051"
"source_system": "api.backend_monitoring"
} ]

start

Unix time when the earliest correlated alert was received

Timestamp (in seconds)

"start": 1466416853

changed_at

Unix time when the last incident change triggered applicable sharing updates

Timestamp (in seconds)

"changed_at": 1466417169

updated_at

Unix time of last change to incident

Timestamp (in seconds)

"updated_at": 1466417169

end

Unix time when the incident was resolved, either manually or automatically when all alerts were resolved

Timestamp (in seconds)

"end": null

alerts

Array of the alerts that the incident contains.

Attributes:
alert_id - System-generated unique identifier for the alert.

When the request comes with expand=alerts, it sends an array of alert object data. See table below for alert object parameters.

Array

"alerts" : [ { "alert_id": "57da76d24cdb1f3a54ce25a0", "alert_id": "68eb89e35dca2g4b65df36b1", "alert_id": "79fc79f46egh3h5c78rg78d2" } ]

assignee

The user assigned responsibility to see an incident through resolution
name - in system name of user
user_id - unique identifier of user
email - email associated with user

Object

"assignee": {
"name": "Bob Bobberson",
"user_id": "21e23r34f4d213e23e",
"email": "[email protected]"

assigner

The user who assigned responsibility for an incident
name - in system name of user
user_id - unique identifier of user
email - email associated with user

Object

"assigner": {
"name": "Bob Bobberson",
"user_id": "21e23r34f4d213e23e",
"email": "[email protected]"

environments

Environment IDs for all environments the incident appears in

Array

"environments": ["607ff43712d7dd0464ebf123", "607ff43712d7dd0464ebf124"]

folders

Folder name of all folders the incident appears in

Array

"folder": ["active", "unhandled"]

incident_tags

Incident tags associated with the incident
id - unique identifier for the tag
name - in system tag name
type - whether the tag is a Text, Priority or MultiValue tag
value - value of the incident tag according to its type

Array

"incident_tags": [
{
"id": "idt_priority",
"name": "priority",
"type": "Priority",
"value": 900
},
{
"id": "affected_services",
"name": "Affected Services",
"type": "MultiValue",
"value": ["Billing"]

Alert Object

Defines the schema for an alert in BigPanda.

Parameters

The Alert object schema includes the following attributes:

Parameter

Description

Type

Example

id

System-generated unique identifier for the alert

String

"id": "60800a8012d7dd0464f1b87d"

status

The most severe status the alert triggered

Possible returns are: critical, warning, unknown, ok

String

"status" : "critical"

start

Unix time when the alert was received

Timestamp (in seconds)

"start": 1466416853

end

Unix time when the alert was resolved

Timestamp (in seconds)

"end": null

changed_at

Unix time when the alert status last changed

Timestamp (in seconds)

"changed_at": 1466417169

updated_at

Unix time of last change to the alert

Timestamp (in seconds)

"updated_at": 1466417169

last_event_at

Unix time of the last alert event

Timestamp (in seconds)

"last_event_at": 1466417169

active

Whether the alert is active and has not been manually resolved.

Boolean

"active": true

primary_property

Main object that triggered the alert

String

“primary_property”: “host”

secondary_property

Secondary object or sub-item that triggered the alert

String

“secondary_property”: “check”

source_system

Integrated monitoring system that sent the alert to BigPanda

String

"source_system": "api.backend_monitoring"

incident_key

A unique id BigPanda uses to recognize if two events are related to each other

String

"incident_key" : “prod-mwv2-demo-1__Host is down”

maintenance_plans

If alert is in maintenance, returns the plan ids

Array

“maintenance_plans”: “60450a8012d7dd0464f1b87dl”

description

Brief summary (max. 2048 characters) of the alert included by certain monitoring tools

String

"description": "CRITICAL - Host Unreachable"

tags

Array of name-value pairs that represent alert properties.

Attributes:
name - Tag name in BigPanda.
value - Tag value in BigPanda.

Note: Tag values are limited to 15 items and/or 512 characters total.

Timestamp (in seconds)

"tags":[ {"name":"host","value":"production-database-1"}, {"name":"check","value":"CPU load"} ]

Search Incidents

GET: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents?query=”{query}”

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

Query Parameters

Parameter

Data Type

Required?

Description

query

String

Not Required

The BPQL query to filter incidents.

Default is All Incidents (“*”)

from

Timestamp (in seconds)

Not Required

Start time of search window. Incidents that were active at any point during the window will be returned.

to

Timestamp (in seconds)

Not Required

End time of search window. Incidents that were active at any point during the window will be returned

Default is query timestamp

sort_by

String

Not Required

Sort option ["last_change", "status",,"start", "alerts"]

Default is last_change

page

Integer

Not Required

What results page should be returned

Default: 1

page_size

Integer

Not Required

How many items per page (min: 1, max: 100)

Default 10

expand

String

Not Required

When set to "alerts" the payload will contain the alerts payload by their schema and not only list of IDs.

folder

String

Not Required

One of: Active, Shared, Snoozed, Resolved, Unhandled, Maintenance

Default Active

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX GET https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents?query=”{query}”
-H 'Authorization: Bearer '

Sample Results

{
  "total": 422,
  "page": 1,
  "items": [
    {
      "id": "60a4ee83bb7d9d046b8d7a93",
      "status": "Ok",
      "active": false,
      "severity": "Critical",
      "flapping": false,
      "shared": false,
      "maintenance": null,
      "start": 1621421699,
      "changed_at": 1629410549,
      "updated_at": 1629410549,
      "end": 1629410549,
      "alerts": [
        {
          "alert_id": "60a4ee83bb7d9d046b8d7a93"
        }
      ],
      "environments": [],
      "folders": [],
      "incident_tags": [],
      "correlation_matchers_log": [
        [
          {
            "time_window": 7200,
            "tags": [
              {
                "name": "case",
                "value": "sensitive1"
              }
            ],
            "correlation_id": "a02fde2f-0ec3-4cc2-9cbd-74895cb13050",
            "source_system": "api.backend_monitoring"
          }
        ]
      ]
  }

Returns

200: Success
{
"total": 123399,
"items" : [
{Incident Object according to the schema},
{Incident Object according to the schema}
]
}

Possible error codes include:

  • 401 Unauthorized - Authentication violation - token is invalid or missing
  • 403 Forbidden— Insufficient permissions
  • 429 Too Many Requests— Rate limitation reached
  • 500 Internal Server Error— Unexpected error

Retrieve Incident by ID

GET: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Not Required

The unique identifier of the incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Sample Results

{
      "id": "60a4ee83bb7d9d046b8d7a93",
      "status": "Ok",
      "active": false,
      "severity": "Critical",
      "flapping": false,
      "shared": false,
      "maintenance": null,
      "start": 1621421699,
      "changed_at": 1629410549,
      "updated_at": 1629410549,
      "end": 1629410549,
      "alerts": [
        {
          "alert_id": "60a4ee83bb7d9d046b8d7a93"
        }
      ],
      "environments": [],
      "folders": [],
      "incident_tags": [],
      "correlation_matchers_log": [
        [
          {
            "time_window": 7200,
            "tags": [
              {
                "name": "case",
                "value": "sensitive1"
              }
            ],
            "correlation_id": "a02fde2f-0ec3-4cc2-9cbd-74895cb13050",
            "source_system": "api.backend_monitoring"
          }
        ]
      ]

Returns

200: Success
{Incident Object according to the schema}

Possible error codes include:

  • 401 Unauthorized - Authentication violation - token is invalid or missing
  • 403 Forbidden— Insufficient permissions
  • 404 Not Found— Entity with this ID cannot be found
  • 429 Too Many Requests— Rate limitation reached
  • 500 Internal Server Error— Unexpected error

Split Incident

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/split

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident

incident_id

String

Required

The ID of a specific incident

Body Parameters

Parameter

Data Type

Required?

Description

comment

String

Not Required

An optional comment to add to the split action

alerts

String

Required

The ID of each alert to split into the new incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX POST https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/split
-H 'Authorization: Bearer'
-H "Content-Type: application/json"
-d {
"comment": "",
"alerts": ["5d09d221aebaec1c43ccd448", "5cff623a21169351a82cb5e2"]
}

NOTES

  • Split actions are heavy asynchronous operations and will have a small delay before being reflected in your data.
  • BigPanda will automatically prevent duplicate split requests. Multiple consecutive attempts to split the same alerts from an incident will result in an error.

Returns

202: Success

Possible error codes include:

  • 401 Unauthorized - Authentication violation - token is invalid or missing
  • 403 Forbidden— Insufficient permissions
  • 404 Not Found— Entity with this ID cannot be found
  • 429 Too Many Requests— Rate limitation reached
  • 500 Internal Server Error— Unexpected error

Merge Incidents

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/merge

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the destination incident

incident_id

String

Required

The ID of a specific incident.

This incident will be the destination incident for the merge.

Body Parameters

Parameter

Data Type

Required?

Description

source_incidents

String

Not Required

A list of incidents to merge into the destination incident defined in the URL path.

comment

String

Not Required

An optional comment to add to the merge action

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX POST https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/merge
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d {
"source_incidents": [
"608ffd7aa912bc031f0ab0f1",
"608ab712fa71ee2824d009c0"
],
"comment": ""
}

NOTES

  • Merge actions are heavy asynchronous operations and will have a small delay before being reflected in your data.
  • BigPanda will automatically prevent duplicate merge requests. Multiple consecutive attempts to merge the same incident with the same source_incidents will result in an error.

Returns

202: Success

Possible error codes include:

  • 401 Unauthorized - Authentication violation - token is invalid or missing
  • 403 Forbidden— Insufficient permissions
  • 404 Not Found— Entity with this ID cannot be found
  • 429 Too Many Requests— Rate limitation reached
  • 500 Internal Server Error— Unexpected error

Comment on Incident

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/comments

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident to be commented on

Body Parameters

Parameter

Data Type

Required?

Description

comment

String

Required

The comment to add to the incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX POST https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/comments
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d '{
"comment": ""
}

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Snooze Incident

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/snooze

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

Body Parameters

Parameter

Data Type

Required?

Description

comment

String

Not Required

An optional comment to add to the Snooze action

end_time

Timestamp (in seconds)

Required

Set a time for the incident to leave the snooze state

cancel_on_incident_updates

Boolean

Not Required

Should the incident become unsnoozed if it is updated?

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX POST https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/snooze
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d '{
"comment": "a comment",
"end_time": 0,
"cancel_on_incident_updates": true
}

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Unsnooze Incident

DELETE: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/snooze

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX DELETE https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/snooze
-H 'Authorization: Bearer '
-H "Content-Type: application/json" \

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Assign Incident

PUT: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/assignment

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

Body Parameters

Parameter

Data Type

Required?

Description

assignee

String

Required

The ID of the user to assign to the incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX PUT https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/assignment
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d '{
"assignee": "AssigneeID"
}

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Unassign Incident

DELETE: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/assignment

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX DELETE https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/assignment
-H 'Authorization: Bearer '
-H "Content-Type: application/json" \

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Add Incident Tags

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/tags

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

Body Parameters

Parameter

Data Type

Required?

Description

tag_id

String

Required

System-generated unique identifier for the incident tag

tag_value

String

Required

The content of the incident tag

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX PUT https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/tags
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d '[
{
"tag_id": "string",
"tag_value": "string"
}
]

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error

Add Incident Tag

POST: https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/tags/{tag_id}

Path Parameters

Parameter

Data Type

Required?

Description

environment_id

String

Required

The ID of the environment that contains the incident(s)

incident_id

String

Required

The ID of the incident

tag_id

String

Required

System-generated unique identifier for the incident tag

Body Parameters

Parameter

Data Type

Required?

Description

tag_value

String

Required

The content of the incident tag

Headers

Header

Data Type

Required?

Description

Authorization

String

Required

User API Key

Example

cURL
curl -iX POST https://api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents/{incident_id}/tags/{tag_id}
-H 'Authorization: Bearer '
-H "Content-Type: application/json"
-d '{
"tag_value": ""
}

Returns

204: Success

Possible response codes include:
401 Unauthorized - Authentication violation - token is invalid or missing
403 Forbidden— Insufficient permissions
404 Not Found—Entity with this ID cannot be found
429 Too Many Requests— Rate limitation reached
500 Internal Server Error— Unexpected error