Introduction to BigPanda APIs
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.
Checkout the BigPanda Postman library here.
Available APIs
The following BigPanda APIs are available:
Integration Configuration APIs
API | Description |
|---|---|
Create and manage configuration for inbound email integrations and Open Integration Manager integrations. | |
Retrieve logs and metrics from various BigPanda integrations. | |
Configure webhooks to build custom integrations with messaging, ticketing, or other collaboration systems. |
Inbound Data APIs
API | Description |
|---|---|
Build a custom integration between BigPanda and your monitoring system or send alerts to the Open Integration Manager via API. | |
Build a custom integration between BigPanda and your monitoring system or send alerts to the Open Integration Manager via API. | |
Connect your organization's change records to BigPanda. |
Alert and Incident Management APIs
API | Description |
|---|---|
Resolve individual alerts in bulk. | |
Retrieve incident data, merge incidents, or add comments to incidents in BigPanda | |
Incidents (Deprecating soon) | Retrieve incident data or update an existing incident. |
AI Configuration
API | Description |
|---|---|
You can use the Automated Incident Analysis API to generate and re-generate incident summaries without using the BigPanda console. |
Enrichment
API | Description |
|---|---|
Define alert tags and enrichment maps that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans. | |
Define alert tags and enrichment maps that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans. | |
Alert Enrichment V1 (Deprecating soon) | Define custom tags that help users understand incidents more quickly and enrich BigPanda functionality, including correlation patterns and maintenance plans. |
Assign tags to your incidents. | |
Configure automatic tag rules. |
System Configuration
API | Description |
|---|---|
Define how alerts are clustered into BigPanda incidents. | |
Define environments and environment groups based on incident properties such as source, severity, or alert data. | |
Define time windows that parallel infrastructure changes of respective monitored services. Manages the suppression-type Maintenance Plans in the UI. | |
Define time windows that parallel infrastructure changes of respective monitored services. Manages the post-enrichment Alert Filtering in the UI. | |
Customize the visual presentation of the topology graph. |
Access Management APIs
API | Description |
|---|---|
Report on changes made to BigPanda resources. | |
Manage user roles within BigPanda. | |
Enables users to provision and manage user accounts and roles. |
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.
All calls to BigPanda use Bearer-type authentication, but the token may have been issued in one of two ways: Org Token or User API Key.
For example:
"Authorization: Bearer ${token}"
"Accept: application/json"
"Content-Type: application/json; charset=utf8"
Org Token vs. User API Key
BigPanda APIs use two different types of bearer tokens, an organization-wide token (Org Token) or a user-specific API Key (API Key).
Org Token
Each organization has a single unique bearer token for authenticating API requests through integrations. To find your org token in BigPanda, log in as an administrator with integrations access and then click the Integrations tab at the top of screen. In the instructions for any integration using the Alerts API, your org bearer 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. Each key is associated to a specific user and is limited by the permissions assigned to the user's roles, enabling improved audit logging and security controls. 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.
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. |
202 Accepted | The request has been accepted for processing. |
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 object 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/alertsTo create an environment using the Environments API:
https://eu-api.bigpanda.io/resources/v2.0/environmentsTo 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/alertsTo subscribe a Datadog topology map:
https://eu.integrations.bigpanda.io/datadog/configure