BigPanda APIs allow you to integrate with external tools and manage incidents and BigPanda elements in bulk. They are a core tool for self-service driven customers, and empower custom solutions and deep 2-way integrations.

Available APIs

The following BigPanda APIs are available:

Inbound Integrations

API	Description	Available Actions
Alerts	Build a custom integration between BigPanda and your monitoring system.	Send Alerts
Changes (RCC)	Connect your organization's change records to BigPanda.	Create/Update a Change Retrieve a Change Retrieve All Changes Create an RCC Relation Retrieve an RCC Relation Retrieve All RCC Relations (for an incident) Update an RCC Relation
Integration Configuration	Create and manage inbound email integrations. Leverages the Email Parser Configuration Object.	Create/Update Email Parser Configuration Retrieve Email Parser Configuration
Troubleshooting	Retrieve logs and metrics from various BigPanda integrations. Leverages the Diagnostics Log Object.	Retrieve All Troubleshooting Logs

Actions

API	Description	Available Actions
Batch Alert Resolver	Resolve individual alerts in bulk.	Resolve Alerts
Incidents V2	Retrieve incident data, merge incidents, or add comments to incidents in BigPanda Leverages the Incident Object, Alert Object, and Activities Object.	Search Incidents Retrieve Incident by ID Split Incident Merge Incidents Comment on Incident Snooze Incident Unsnooze Incident Assign Incident Unassign Incident Add Incident Tags Add Incident Tag Get Activities
Incidents (Deprecating soon)	Retrieve incident data or update an existing incident. Leverages the Incident Object and Alerts Object.	Retrieve an Incident Resolve/Comment Incident

Platform Configuration

API	Description	Available Actions
Correlation Patterns	Define how alerts are clustered into BigPanda incidents. Leverages the Correlation Patterns Object.	Create Correlation Pattern Retrieve a Correlation Pattern by ID Retrieve all Correlation Patterns Update Correlation Pattern Delete Correlation Pattern
Environments	Define incident groups based on incident properties such as source, severity, or alert data. Leverages the Environments Object.	Create an Environment Retrieve an Environment by ID Retrieve All Environments Update Environment Delete Environment
Maintenance Plans V2	Define time windows that parallel infrastructure changes of respective monitored services. Leverages the Maintenance Plans Object.	Create a Plan Retrieve a Plan Retrieve All Plans Update a Plan Delete a Plan Stop Plan
Maintenance Plans V1	Define time windows that parallel infrastructure changes of respective monitored services. Leverages the Plans Object.	Create a Plan Retrieve a Plan Retrieve All Plans Update a Plan Delete a Plan
Schedules V1	Schedules are a secondary feature to the Plans API and allow for the definition of explicit start and stop times. Leverages the Schedule Object.	Create a Schedule Retrieve a Schedule Retrieve All Schedules Update a Schedule Delete a Schedule
Topology UI	Customize the visual presentation of the topology graph. Leverages the Topology UI Object.	Create Topology Retrieve a Topology Retrieve All Topologies Update a Topology Delete a Topology

Enrichment

API	Description	Available Actions
Enrichment V2	Define alert tags and enrichment maps that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans. Leverages the Enrichments Object.	Create Alert Enrichment Item Update Alert Enrichment Item Delete Alert Enrichment Item Retrieve Alert Enrichment Item List All Enrichment Items of a Tag List All Alert Tags Retrieve Tags Order Update Tag Order Retrieve Enrichment Item Order Update Enrichment Items Order Create Mapping Enrichment Table Rows Update Mapping Enrichment Table Rows Retrieve Mapping Enrichment Check Status of Upload Job
Enrichments V1 (Deprecating soon)	Define custom tags that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans. Leverages the Enrichments Object.	Create Enrichment Retrieve Enrichment Update Enrichment Delete Enrichment List All Enrichments Create Mapping Enrichment Table Update Mapping Enrichment Table Rows Retrieve Mapping Enrichment Check Status of Upload Job
Incident Tags	Assign tags to your incidents. Leverages the Incident Tags Object.	Add an Incident Tag to an Incident Add Multiple Incident Tags to an Incident Retrieve an Incident Tag from an Incident Retrieve All Tags for an Incident Delete an Incident Tag from an Incident Delete All Tags for an Incident
Incident Tags Definitions	Assign tags to your incidents. Leverages the Incident Tags Definitions Object.	Create an Incident Tag Definition Retrieve an incident tag definition Retreieve all incident tags definitions Update an Incident Tag Definition

User Access Management

API	Description	Available Actions
Audit Logs	Report on changes made to BigPanda resources. Leverages the Audit Log Object.	Retrieve all Audit Logs
Roles	Manage user roles within BigPanda. Leverages the Roles Object.	Create a Role Retrieve All Roles Update a Role Delete a Role Retrieve Role by ID
SCIM Users	Enables users to provision and manage user accounts and roles. Leverages the Service Provider Config Object and the User Object.	Retrieve Service Provider Configuration Retrieve User Schema Retrieve All Schemas Retrieve User by ID Retrieve Users Create Users Update a User Delete a User

Authentication and Headers

With each request to the BigPanda API, you must include an HTTP header with the authentication token for your organization. You may also need to specify the content type of the data payload and/or the response payload.

For example:

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

Org Token vs. API Key

BigPanda APIs use two different types of authentication tokens, an organization-wide bearer token or a user-specific API Key

Org Token

Each organization has a unique bearer token for authenticating API requests. To find your token in BigPanda, log in as an administrator with integrations access 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.

User API Keys

API Keys are managed on a user-specific basis within BigPanda's API Keys settings menu. To learn more about using User API Keys, see the API Key Management documentation.

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.

Generating Sample Code

Each API endpoint is located on a single page, making it easy to find specific code samples and required fields. Full code samples can be generated right in the API reference pages using interactive fields for each endpoint parameter. Code samples are created automatically in several different languages with the defined parameters filled in.

📘
Formatting Note
All timestamp fields should be in Epoch format, and should not include milliseconds.

Example of an API endpoint with sample code

To generate sample code:

Navigate to the appropriate API endpoint page.
Type the relevant information into each endpoint parameter box.
Scroll to the top right of the page above the code box and click the three dots icon.
Select the appropriate language from the menu. The system will remember your selected language on other API endpoint pages.
(Optional) Click the down arrow icon and select a language variant from the menu. The system will remember your selected language variant on other API endpoint pages. When selecting one of our example payloads such as the Default or EU variants, the interactive fields will not update in the code sample.

⚠
️
If you are using BigPanda APIs in Europe, select the EU language variant from the Shell menu. EU code requires an endpoint prefix that will not be included in other examples.

Click the Clipboard icon to copy the code.

⚠
️
BigPanda recommends adding Authentication headers only in the secure tool you use to make API calls

Response Codes

BigPanda uses conventional HTTP response codes to indicate the success or failure of an API request. When a request is successful, BigPanda sends a response code to indicate that it received the message. If a request fails, the response code may help with troubleshooting an error.

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.

Response	Description
`200 OK`	Success.
`201 Created`	New resource created.
`204 No Content`	There is no content to send for this request.
`400 Bad Request`	Default code for invalid requests. For example, it is missing a mandatory field. Check the error message and ensure that the JSON includes the correct parameters.
`401 Unauthorized`	Token is invalid or missing. Check that the request includes the correct HTTP headers.
`403 Forbidden`	Access denied.
`404 Not Found`	Requested endpoint isn't available. Ensure that the request uses one of the API endpoints specified in the documentation.
`409 Conflict`	Request cannot be performed due to a conflict. For example, attempting to resolve an incident that's already resolved.
`410 Gone`	Requested resource is no longer available and has been removed permanently. Consult the documentation to see what endpoints are supported currently.
`500 Internal Server Error`	Default code for errors that occur due to problems on BigPanda servers. Retry the request after some time.
`501 Not Implemented`	Unsupported method.

Expandable Objects

Some objects contain the ID of a related object in their response properties. For example, an Incident may have associated Alert IDs. If the object is expandable, you can use the expand query parameter in your request to retrieve a full representation of it.

For example, append ?expand=alerts to the URL 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 expand property in the parent object. You can expand multiple objects at once by identifying multiple items in the expand array.

Synchronous and Asynchronous Calls

API requests for potentially long-running actions are performed asynchronously.

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}

Migrating to New API Versions

BigPanda is constantly improving our APIs for better functionality, reliability, and usability. While most of our updates are seamless and require no changes, occasionally a whole new API version is necessary.

If you were using the older version, migrating to a V2 API only takes a few simple steps:

Update the call base URL.
Validate the Authentication Type - All new APIs require authentication through User API Key. If your previous APIs was leveraging the Org Token, you'll need to issue and update new credentials.
Validate body fields or values - While we strive to keep payloads consistent, sometimes a change is necessary to make space for new or improved functionality. Always review payloads to ensure they match new parameters.
(Optional) Set pagination or filter rules - Some GET calls now have pagination or filtering enabled to improve readability, response times, and reliability. For large data sets, you may need to configure filters or pagination, and scripted recurring calls to retrieve all data.
Test the API - As when making any changes to your BigPanda configuration, we recommend sending sample API calls to test the changes.

Using BigPanda REST APIs in Europe

To enable BigPanda APIs in the EU, an additional prefix should be added at the beginning of the base API URL:

eu-

For example:

To call the Alerts API: https://eu-api.bigpanda.io/data/v2/alerts
To create an environment using the Environments API: https://eu-api.bigpanda.io/resources/v2.0/environments
To search using the Incidents API: https://eu-api.bigpanda.io/resources/v2.0/environments/{environment_id}/incidents?query=”{query}”

Code samples containing the eu- prefix in the base API URL can be automatically created in each API endpoint documentation page. To generate the sample code, in the upper right of the code box, click the down arrow. Select EU from the list of variants.

When working with Integrations, you will instead need to prefix URLs with eu.

For example:

To send an alert to an OIM integration: https://eu.integrations.bigpanda.io/oim/api/alerts
To subscribe a Datadog topology map: https://eu.integrations.bigpanda.io/datadog/configure

Introduction to BigPanda APIs

Available APIs

Inbound Integrations

Actions

Platform Configuration

Enrichment

User Access Management

Authentication and Headers

Org Token vs. API Key

Org Token

User API Keys

Content Types

Generating Sample Code

📘
Formatting Note

⚠
️

⚠
️

Response Codes

Expandable Objects

Synchronous and Asynchronous Calls

Migrating to New API Versions

Using BigPanda REST APIs in Europe

Available APIs

Inbound Integrations

Actions

Platform Configuration

Enrichment

User Access Management

Authentication and Headers

Org Token vs. API Key

Org Token

User API Keys

Content Types

Generating Sample Code

📘Formatting Note

⚠️

⚠️

Response Codes

Expandable Objects

Synchronous and Asynchronous Calls

Migrating to New API Versions

Using BigPanda REST APIs in Europe

📘
Formatting Note

⚠
️

⚠
️