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.

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 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.

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 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.

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}