API - Incidents

1. In LinearB, go to Company Settings → Project Management → Incidents.
2. In the Incidents Detection section, select API Integration.
3. 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.

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.

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

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

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

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

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

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.

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

1. Navigate to Metrics → Git Activity → Incidents.
2. 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.

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.

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

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

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

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

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