LinearB Incident API: Setup and Best Practices

Configuring the Incident API

Step 1: Enable the API Integration

1. Generate a LinearB API Token.
2. Navigate to Company Settings > Advanced
3. In the Releases Detection section, select the API Integration option.
4. Click Save to apply your changes.

Step 2: Start Sending Incident Data

Once the integration is enabled, you can begin sending incident data to the API. Below, you'll find examples to help you get started quickly.

How to Use the Incident API

Creating a New Incident

To create a new incident using the Incident API, ensure you provide the following required fields:

• provider_id:
  A unique identifier assigned by the third-party incident reporting tool. This ensures accurate mapping between LinearB and the external provider.
• http_url:
  The URL of the incident's web page in the third-party system, allowing quick access to detailed information about the incident.
• title:
  The title of the incident. For consistency and clarity, it’s recommended to match the title from the third-party provider.
• issued_at:
  The timestamp indicating when the incident was created. This must be in ISO 8601 format to ensure proper parsing and accuracy.

Example Payload:

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.

Managing Incidents with the LinearB API

Retrieving Incident Details

To retrieve information about an existing incident, send a GET request to the incident endpoint. Replace PROVIDER_ID with the unique identifier from your third-party incident management tool.

Example Command:

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" 

Updating an Existing Incident

After an incident is created, keep it up-to-date by providing timestamps for when work begins and ends.

• Mark an Incident as Started: Send a PATCH request with an ISO 8601 timestamp in the started_at field.

Example Command:

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"
}'

• Mark an Incident as Finished: Send another PATCH request, this time including an ISO 8601 timestamp in the ended_at field.

Example Command:

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"
}'

Deleting an Incident

To delete an existing incident, send a DELETE request to the incident endpoint, replacing PROVIDER_ID with the appropriate identifier from your third-party system.

Example Command:

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" 

Notes

• Replace YOUR_API_KEY with your LinearB API key for authentication.
• Use PROVIDER_ID to identify the specific incident you’re managing.
• Ensure all timestamps follow the ISO 8601 format (e.g., YYYY-MM-DDTHH:MM:SSZ).

Best Practices for Using the Incident API

Keep Incident Data Up to Date

• Utilize the Update Incident Call:
  After detecting an incident, ensure LinearB receives updates to track associated services, repositories, teams, and resolution times.
  • Ensure your project management (PM) tool also updates resolution times accurately to provide a precise Mean Time to Recovery (MTTR).

Report Incidents Retroactively

• Missed Incident Reporting? No Problem!
  If an issue is resolved before a ticket is created (we’ve all been there), use the Incident API to retroactively report incidents. This ensures timestamps remain accurate and the data is complete.

Viewing Incident Data

1. Incidents Tab

1. Navigate to the Metrics > Git Activity > Incidents to view all incidents collected through the API.
2. Use filters to focus on specific incidents.

2. Metrics Dashboard

• Incidents reported via the API are reflected in the Change Failure Rate (CFR) and Mean Time to Recovery (MTTR) widgets on the Metrics Dashboard.
• Click on any date within these graphs to drill down into the corresponding incident details in the Git Activity Releases tab.

By accessing these tabs, you can monitor incident data, analyze trends, and assess team performance based on your reported incidents.

Configuring the Incident API for Individual Teams

In some organizations, teams may require a different incident detection method than the organization's default. For example, if your team prefers to use the Incident API while the company is configured to rely on incidents reported by a project management tool, you can override the default settings.

To configure the Incident API for your team:

1. In the LinearB side menu, click Settings > Company Settings.
2. Select the team that will use a different incident detection method from the organization's default.

1. In the Team Settings page, click the Project Management tab, and then click the Incidents tab.
2. Select the API Integration option.
3. Click Save.

1. Follow the previously outlined steps to enable and report incidents using the API.

This customization allows teams to tailor their incident detection process while remaining aligned with organizational goals.