Incident API – Configure Incident Detection for DORA Metrics

• Enable Incident API detection under Company Settings → Project Management → Incidents.
• Create incidents with a POST request and keep them updated via PATCH.
• Retrieve or delete incidents using GET and DELETE endpoints.
• View reported incidents in Metrics → Git Activity → Incidents and in DORA widgets.
• Optionally override incident detection per team.

1. Generate a LinearB API token .
2. Go to Company Settings → Project Management, and open the Incidents tab.
3. In Incidents Detection, select API Integration.
4. Click Save.

After the integration is enabled, you can begin sending incident data to the Incident API. The examples below show the most common operations.

To create a new incident, include at least the following fields:

• provider_id
  A unique identifier from your incident system (used to map the incident in LinearB).
• http_url
  A link to the incident in the external system (for quick navigation).
• title
  The incident title. For clarity, use the same title as the external provider.
• issued_at
  The creation timestamp in ISO 8601 format.

Example

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

For the full list of required and optional fields, see the API reference documentation .

To retrieve an incident, send a GET request using its provider_id.

Example

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"

Keep incidents up to date by patching timestamps for when work starts and ends. Use ISO 8601 timestamps.

Mark an incident as started

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

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

To delete an incident, send a DELETE request using its provider_id.

Example

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.
• Replace PROVIDER_ID with the identifier from your incident system.
• Use ISO 8601 timestamps (for example, YYYY-MM-DDTHH:MM:SSZ).

• Keep incidents current: update started_at and ended_at so CFR/MTTR reflects reality.
• Report incidents retroactively: if a ticket is created after resolution, you can still submit the incident with accurate timestamps.

Incidents page

1. Go to Metrics → Git Activity → Incidents.
2. Use filters to focus on relevant incidents.

Metrics dashboard

• API-reported incidents appear in the CFR and MTTR widgets on the Metrics dashboard.
• Click a date in the chart to drill down into the corresponding incident details.

If a team needs a different incident detection method than the organization default, you can override incident detection at the team level (for example, the org uses a PM tool, but a specific team uses the Incident API).

1. In the LinearB side menu, click Settings → Company Settings.
2. Select the team that requires a different incident detection method.
3. Open Team Settings → Project Management → Incidents.
4. Select API Integration.
5. Click Save.
6. Report incidents using the Incident API as described above.