Incidents API – LinearB Support

The LinearB Incident API lets you send incident data to LinearB so the platform can accurately calculate Change Failure Rate (CFR) and Mean Time to Recovery (MTTR). By integrating your incident source with LinearB, you can complete your DORA metrics and monitor production stability across teams, services, and repositories.

TL;DR

Use POST /api/v1/incidents to create incidents from any incident or PM tool.
Use PATCH /api/v1/incidents/{provider_id} to update timestamps, services, repos, and teams.
Use POST /api/v1/incidents/search to find incidents by time range, status, repos, teams, or services.
Use GET /api/v1/incidents/{provider_id} to retrieve details for a single incident.
Use DELETE /api/v1/incidents/{provider_id} to remove an incident.
Incidents reported via the API feed directly into CFR and MTTR on the Metrics dashboard.

Where to Configure Incident Detection

Set the organization-wide incident detection method

In LinearB, go to Company Settings → Project Management → Incidents.
In the Incidents Detection section, select API Integration.
Click Save to apply your changes.

Once API Integration is selected at the organization level, incidents reported via the API are used to calculate CFR and MTTR for your LinearB environment.

(Optional) Override org-wide settings by customizing incident configure by team

Override incident detection per team

Individual teams can use a different incident detection method than the organization default. For example, the org may use project-management–based incidents, while a specific team uses the Incident API.

In LinearB, select the team from the dropdown (top right corner) that should use different detection rules.
On the Team Settings page, open the Project Management tab, then click the Incidents tab.
Select API Integration.
Click Save.

This affects how LinearB calculates CFR and MTTR for that team and any parent groups that aggregate it.

Before You Begin

Required access: LinearB Admin (for configuration and API token creation).
API access enabled for your LinearB organization.
Ability to:
- Generate and securely store a LinearB API key.
- Access your incident management or PM tool (for provider IDs and URLs).
Ensure your incident source can send:
- A unique provider_id per incident.
- An http_url that opens the incident in your provider.
- ISO 8601 timestamps for issued_at, started_at, and ended_at (when used).

Authentication

All Incident API requests must include your LinearB API key.

In LinearB, create an API key (API token) for your integration.
Include it in each request using the x-api-key header:

x-api-key: YOUR_API_KEY

Content-Type: application/json

Create Incident

POST /api/v1/incidents

Create a new incident in LinearB. This is typically called from your incident tool or automation when an incident is opened.

HTTP request

POST https://public-api.linearb.io/api/v1/incidents

Body parameters

Field	Type	Required?	Description
`provider_id`	string (max 255 chars)	Yes	Unique identifier of the incident in your incident or PM provider.
`http_url`	string (max 512 chars)	Yes	URL of the incident in your provider. The combination of `http_url`/`provider_id` should open the incident.
`title`	string (max 255 chars)	Yes	Incident title. For clarity, use the same title as your incident tool.
`issued_at`	string (ISO 8601)	Yes	Time the incident was logged and officially opened.
`started_at`	string (ISO 8601)	No	Time work on the incident began.
`ended_at`	string (ISO 8601)	No	Time the incident was successfully resolved.
`git_ref`	string	No	Git ref of the release that caused the incident (commit SHA or tag name).
`teams`	array of strings (lowercase)	No	List of LinearB team names related to this incident.
`services`	array of strings (lowercase)	No	List of LinearB service names related to this incident.
`repository_urls`	array of strings	No	List of repository URLs related to this incident.

Example: reporting a new incident (request body)

{
  "provider_id": "provider_internal_id1",
  "http_url": "http://myprovider.io/1",
  "title": "This is critical production bug",
  "issued_at": "2019-09-26T07:58:30.996",
  "teams": [
    "team a",
    "team b"
  ],
  "repository_urls": [
    "https://github.com/myorg/repo1.git",
    "https://github.com/myorg/repo2.git"
  ]
}

Responses

201 – Incident created successfully.
400 – Bad Request (invalid payload).
401 – Unauthorized (missing/invalid API key).
405 – Method Not Allowed.
422 – Validation Error (see response body for details).
500 – Internal Server Error.

Update Incident

PATCH /api/v1/incidents/{provider_id}

Update an existing incident in LinearB. Use this to set or modify timestamps, related repos, teams, and services as the incident progresses.

HTTP request

PATCH https://public-api.linearb.io/api/v1/incidents/{provider_id}

Body parameters (all optional unless noted in your workflow)

Field	Type	Description
`title`	string (max 255 chars)	Updated title of the incident.
`issued_at`	string (ISO 8601)	Time the incident was logged/opened.
`started_at`	string (ISO 8601)	Time work on the incident started.
`ended_at`	string (ISO 8601)	Time the incident was resolved.
`git_ref`	string	Git ref of the release associated with the incident (commit SHA or tag name).
`teams`	array of strings (lowercase)	List of LinearB team names related to this incident.
`services`	array of strings (lowercase)	List of LinearB service names related to this incident.
`repository_urls`	array of strings	List of repository URLs related to this incident.

Example: mark incident as started (request body)

{

  "started_at": "2024-01-27T17:18:36Z"

}

Example: mark incident as finished (request body)

{

  "ended_at": "2024-01-27T17:18:36Z"

}

Responses

204 – Incident updated successfully.
400 – Bad Request.
401 – Unauthorized.
405 – Method Not Allowed.
422 – Validation Error.
500 – Internal Server Error.

Search Incidents

POST /api/v1/incidents/search

Search incidents saved in LinearB by time range, status, repositories, teams, or services.

HTTP request

POST https://public-api.linearb.io/api/v1/incidents/search

Request body filters

Field	Type	Description
`teams`	array of strings (lowercase)	List of LinearB team names related to incidents.
`services`	array of strings (lowercase)	List of LinearB service names related to incidents.
`repository_urls`	array of strings	List of repository URLs related to incidents.
`issued_at`	object	Time window for when the incident was logged. Supports `{"after": "...", "before": "..."}` (ISO 8601 date strings).
`started_at`	object	Time window for when work started on the incident.
`ended_at`	object	Time window for when the incident was resolved.
`statuses`	array of strings (lowercase)	Incident status filter. Valid values: `"open"`, `"in-progress"`, `"closed"`, `"deleted"`.
`sort_by`	string	Sort field. Valid values: `"issued_at"`, `"started_at"`, `"ended_at"`. Default: `"issued_at"`.
`sort_dir`	string	Sort direction. Valid values: `"desc"`, `"asc"`. Default: `"desc"`.
`limit`	integer	Maximum number of incidents to return (1–100). Default: `25`.
`offset`	integer	Offset for pagination. Default: `0`.

Example: open incidents after a date

{

  "limit": 50,

  "issued_at": {

    "after": "2021-12-01"

  },

  "statuses": [

    "open"

  ]

}

Example: uncompleted incidents between dates for a specific repo

{

  "limit": 50,

  "issued_at": {

    "after": "2021-01-01",

    "before": "2022-12-31"

  },

  "repository_urls": [

    "https://github.com/myorg/website.git"

  ],

  "statuses": [

    "open",

    "in-progress"

  ]

}

Responses

200 – Successful Response (returns total and items array).
400 – Bad Request.
401 – Unauthorized.
404 – Not Found.
405 – Method Not Allowed.
422 – Validation Error.
500 – Internal Server Error.

Get Incident

GET /api/v1/incidents/{provider_id}

Retrieve a single incident by its provider_id.

HTTP request

GET https://public-api.linearb.io/api/v1/incidents/{provider_id}

Path parameter

provider_id (string, max 255 chars) – Unique identifier of the incident in your incident/PM provider.

Responses

200 – Returns the full incident record (provider_id, http_url, title, timestamps, git_ref, teams, services, repositories, status).
400 – Bad Request.
401 – Unauthorized.
404 – Not Found.
405 – Method Not Allowed.
422 – Validation Error.
500 – Internal Server Error.

Delete an Incident

DELETE /api/v1/incidents/{provider_id}

Delete an incident by its provider_id.

HTTP request

DELETE https://public-api.linearb.io/api/v1/incidents/{provider_id}

Path parameter

provider_id (string, max 255 chars) – Unique identifier of the incident in your incident/PM provider.

Responses

204 – Incident deleted successfully.
400 – Bad Request.
401 – Unauthorized.
405 – Method Not Allowed.
422 – Validation Error.
500 – Internal Server Error.

Viewing Incident Data in LinearB

1. Incidents tab

Navigate to Metrics → Git Activity → Incidents.
Use filters to focus on specific teams, services, or repositories.

Incidents roll up from sub-teams to parent groups.
For example, if Group A includes Teams B and C, Group A’s incidents include data from both teams.

2. Metrics dashboard (CFR & MTTR)

Incidents reported via the API are reflected in the Change Failure Rate (CFR) and Mean Time to Recovery (MTTR) widgets on the Metrics dashboard.

Use CFR to understand how often deployments cause incidents.
Use MTTR to understand how quickly incidents are resolved.
Click any date within these graphs to drill into incident details in the Git Activity Releases/Incidents views.

Best Practices

Keep incident data up to date
- Update started_at when work begins and ended_at when the incident is resolved.
- Populate teams, services, and repository_urls for accurate aggregation.
Use the Update Incident endpoint
- Don’t create duplicate incidents for the same event — update the existing record via PATCH.
- Ensure resolution times are reflected both in LinearB and (if applicable) in your PM tool.
Report incidents retroactively when needed
- If an issue is resolved before a ticket is formally created, you can still use the Incident API to backfill it.
- Provide correct issued_at, started_at, and ended_at to keep MTTR accurate.
Align with your CFR/MTTR strategy
- Use consistent rules for what counts as an “incident” across teams.
- Combine Incident API usage with Deployment tracking so incidents are correctly linked to releases.

Troubleshooting & FAQ

Authentication errors (401)

Confirm you’re sending x-api-key with a valid LinearB API key.
Check that the key belongs to the correct LinearB organization.
Verify there is no proxy or gateway stripping headers.

Validation errors (422)

Ensure required fields are present for create:
- provider_id
- http_url
- title
- issued_at (ISO 8601)
Verify that date fields (issued_at, started_at, ended_at) use ISO 8601 format.
Check error details in the response body (detail array) for the exact field causing issues.

Incidents not appearing in the UI

Confirm that Company Settings → Project Management → Incidents is set to API Integration or that your team overrides are configured to use the API.
Verify that your filters (teams, services, date range) in the UI match the data you’re sending.
Use GET /api/v1/incidents/{provider_id} or /incidents/search to confirm the incident exists in LinearB.

Why do incidents affect CFR & MTTR?

CFR (Change Failure Rate) – uses incidents to determine how often changes result in failures.
MTTR (Mean Time to Recovery) – uses issued_at and ended_at (and related logic) to measure recovery time.
If incidents are missing or incomplete, CFR/MTTR will be inaccurate.

Time format requirements

All timestamps must follow ISO 8601, for example: 2024-01-25T17:18:36Z.
Inconsistent formats are a common cause of 422 Validation Errors.

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.

TL;DR

Once API Integration is selected at the organization level, incidents reported via the API are used to calculate CFR and MTTR for your LinearB environment.

Before You Begin

Authentication

1. Incidents tab

2. Metrics dashboard (CFR & MTTR)

Best Practices

Troubleshooting & FAQ

Related articles