LinearB Incident API

LinearB's incident API allows you to send incident data to LinearB in order to capture an accurate CFR and MTTR metric. Incidents can be tracked from any project or incident management tool using this method.

Incident API Configuration

1. Generate a LinearB API Token
2. Enable the API Integration by going to Company Settings -> Advanced Settings -> Incidents Detection. Remember to click Save!

   1. 

3. Start sending incident data to the API! You can find some examples below.

How to Use the Incident API

Create a New Incident

To create a new incident, you must provide the following fields:

• provider_id - The unique identifier provided by the third party incident reporting tool.
• http_url - A URL that points to the web page for the incident.
• title - The incident title, we recommend matching the title from the third party provider.
• issued_at - A timestamp in iso 8601 format that specifies when the incident was created.

curl -X POST "https://public-api.linearb.io/api/v1/incidents" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "provider_id": "B1BUOEOBKNAHKG",
  "http_url": "https://acme.pagerduty.com/incidents/B1BUOEOBKNAHKG",
  "title": "[#1] My First Incident",
  "issued_at": "2024-01-25T17:18:36Z"
}'

Review the API reference docs for a complete list of required and optional fields.

Get Info About Existing Incidents

To get information about an existing incident, send a GET request to the incident endpoint and provide the ID from the third-party incident management service. In this next example, replace PROVIDER_ID with the appropriate value for your incident.

curl -X GET "https://public-api.linearb.io/api/v1/incidents/PROVIDER_ID" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" 

Update an Existing Incident

Once an incident is created, you'll also want to update it when someone starts working on it, and when it's finished. To update an existing incident, send a PATCH request to the incident endpoint and specify the third-party provider ID and provide an ISO 8601 timestamp for the started_at field:

curl -X PATCH "https://public-api.linearb.io/api/v1/incidents/PROVIDER_ID" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "started_at": "2024-01-27T17:18:36Z"
}'

Then, when the incident is finished, you can inform LinearB using the same convention, but this time, you need to specify a value for ended_at:

curl -X PATCH "https://public-api.linearb.io/api/v1/incidents/PROVIDER_ID" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "ended_at": "2024-01-27T17:18:36Z"
}'

Delete an Incident

To delete an existing incident, send a DELETE request to the incident endpoint and provide the ID from the third-party incident management service. In this next example, replace PROVIDER_ID with the appropriate value for your incident.

curl -X DELETE "https://public-api.linearb.io/api/v1/incidents/PROVIDER_ID" \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" 

Best Practices

• Utilize the update instance call!
  • Once an incident is detected, LinearB will need updates to track services, repos, teams, and resolution time. Make sure your PM tool is also updating resolution times in order to get an accurate MTTR.
• Incidents can be reported retroactively!
  • Sometimes things get fixed before a ticket is even created (we know, we do it too). Use the incident API to report incidents after they've occurred, ensuring you can report appropriate/correct timestamps.

Where can I see my incidents?

Activity Tab

You can see all incidents collected via the incidents API from your Activity Tab. Select the "Incidents" view to see and filter incidents.

Metrics Tab

Incidents collected will be reflected in your CFR and MTTR widgets in your Metrics reports. Click on any date within these graphs to go to the incidents report in your Activity tab.

CFR and MTTR will be calculated based on the incidents sent to LinearB

Configuring the Incident API Per-team

In many organizations, the incident detection pattern for individual teams may vary from the organization's default. If your team wishes to use the Incident API when the larger company is configured to use issues reported by your project management tool, that is possible.

To override that setting, go to the Teams Settings page. From there, select the API Integration radio button, and you should be able to follow the steps above in order to report your incidents.