Skip to main content
Table of Contents

API - Start Here

The LinearB API gives you full control to integrate deployments, incidents, measurements, custom metrics, teams, services, and users with your internal systems. This hub provides everything you need…

Table of Contents

The LinearB API gives you full control to integrate deployments, incidents, measurements, custom metrics, teams, services, and users with your internal systems. This hub provides everything you need to get started, including authentication, common tools, troubleshooting, and links to each API’s dedicated guide.

API Overview

The LinearB API is organized around resource-specific endpoints. Each resource has its own dedicated guide, linked below, using a standardized format with Overview, Before You Begin, Steps, Verify, Troubleshooting, and FAQs.

  • Deployments API — report releases or deployments to LinearB.
  • Incidents API — send incident start/end data for CFR and MTTR.
  • Measurements v2 API — push engineering measurements.
  • Services API — register or update services and monorepo service boundaries.
  • External Custom Metrics API — push business or delivery metrics.
  • Teams v2 API — create or update team structures.
  • Users API — manage contributors and profile data.

View the LinearB Public API Reference →

Authentication and API Tokens

How Authentication Works

LinearB APIs require an API token generated inside the LinearB application. Your token determines:

  • Which resources you can access
  • Whether you can read or write data
  • Which organization the request applies to

Use the authentication scheme documented for the endpoint you are calling.

For example, the Users API requires the following header: 

x-api-key: <your_api_token>

Create an API Token

  1. Go to Company Settings → API Tokens.
  2. Click Generate New Token.
  3. Name your token.
  4. Copy it and store it securely. This is your only opportunity to see the raw value.

Note: API tokens inherit the applicable LinearB privileges.

Securing Tokens

  • Rotate tokens regularly.
  • Store them in a vault such as 1Password, AWS Secrets Manager, or HashiCorp Vault.
  • Do not place tokens in source code or share them in support messages.
  • Revoke tokens immediately if exposed.

Tools and Utilities

Job Status API

Use this endpoint to check the status of asynchronous API operations, such as imports, background processing, or long-running tasks.

Endpoint

GET /v1/jobs/{job_id}

Common statuses

  • queued — the job is waiting to be processed.
  • running — the job is currently being processed.
  • succeeded — the job completed successfully.
  • failed — the job encountered an error.
Health Check API

Use this endpoint to verify whether the LinearB API is reachable and responding.

Endpoint

GET /v1/health

Expected behavior

  • A healthy response returns 200 OK.
  • The response body may include a status indicator, such as status: "ok".
API Test Client

Use the built-in API Explorer to test endpoints and validate your configuration.

  • Send authenticated GET and POST requests
  • View sample payloads and responses
  • Validate your API token and organization ID

Location
In the LinearB app, go to Company Settings → API Explorer.

General API Verification and Troubleshooting

Verify API health
  1. Send a request to the health endpoint: GET /v1/health.
  2. Confirm that you receive a 200 OK response.
  3. Review the response body for an overall status indicator, such as status: "ok", if provided.
  4. If you use monitoring or alerting, configure it to call this endpoint regularly and alert on non-2xx responses.
Verify job status
  1. Trigger an action that returns a job_id, such as a bulk import or long-running API operation.
  2. Copy the job_id from the response.
  3. Poll the Job Status API: GET /v1/jobs/{job_id}.
  4. Confirm that the job transitions through the expected states: queued → running → succeeded or failed.

Quick fixes for common issues

  • Health check returns 401 or 403
    — Authentication or authorization is failing.
    — Check the current API reference and confirm that the token is being sent in the required header.
    — Confirm that the token is valid and belongs to the correct organization.
  • Health check returns 5xx or a degraded status
    — One or more backend components may be temporarily unavailable or under load.
    — Retry after a short delay. If the issue persists, check the LinearB status page or contact your CSM or LinearB Support.
  • Job stays in queued for too long
    — The worker queue may be busy, or the job may not yet have been picked up.
    — Compare the duration with typical queue times for your environment. If it is unusually long, capture the job_id and contact support.
  • Job stays in running for too long
    — The job may be processing a large dataset or long-running operation.
    — If it exceeds its normal duration, capture the job_id and share it with your CSM or LinearB Support.
  • Job status is failed
    — The job encountered a validation or processing error.
    — Inspect the response for an error message or code, correct the underlying payload, configuration, or upstream-system issue, and trigger a new job.

Advanced troubleshooting

Use this matrix when health-check or job-status results still do not match expectations.

Problem Cause Fix
Health endpoint returns 401 or 403 Authentication or authorization issue:
  • Missing or invalid API token
  • The token belongs to a different environment or organization
  • The request uses the wrong authentication header
 Check the endpoint’s current API reference and use the authentication header it specifies.
Confirm that the token belongs to the organization and environment being monitored.
Health endpoint returns 5xx or a degraded status One or more backend services may be unavailable, under maintenance, or under heavy load. Retry after a short delay.
If the issue persists, check the LinearB status page or contact your CSM or LinearB Support with timestamps and response details.
Job is stuck in queued The job has not yet been picked up by a worker, often because of high load or the number of queued jobs. Wait a few minutes and poll again.
If the job remains queued for an unusually long time, capture the job_id and approximate start time and share them with support.
Job is stuck in running The job is still processing, or an internal step is slow or blocked. Compare the runtime with similar jobs to understand the typical duration.
If the job is an outlier, capture its job_id and context and contact support.
Job ends in failed The submitted work encountered a validation or processing error, such as an invalid payload, missing reference, or upstream failure. Inspect the job-status response for an error message or code.
Fix the payload, references, or configuration, then start a new job and monitor its status.
Jobs succeed, but data seems to be missing The job completed successfully, but:
  • The configured scope, such as time range, team, or project, did not match what you expected.
  • Dashboard filters may exclude the processed data.
Confirm what the job was configured to process.
Adjust dashboard or report filters to match that scope, or rerun the job with corrected parameters.

API Reference Articles

Open a section below to learn more about each API.

1. API Overview

LinearB provides APIs that let you:

  • Report deployments programmatically
  • Send incidents for CFR and MTTR
  • Track custom KPIs and measurements
  • Define services for deployment filtering
  • Create and manage teams and contributors programmatically

Refer to the public API reference for the authentication requirements of the endpoint you are calling.

Where to create API tokens:
Go to Company Settings → API Tokens.


2. Deployments API

The Deployments API lets you tell LinearB when a deployment occurs so it can close out cycle time, calculate Lead Time, and match deployed PRs using Git ancestry logic.

Why use it

  • Precise deployment detection for DORA
  • Required for CFR and MTTR when using API-only incident mode
  • Useful for custom pipelines or monorepos

Read the Deployments API Guide →


3. Incidents API

The Incidents API enables LinearB to calculate Change Failure Rate (CFR) and Mean Time to Recovery (MTTR) using incidents reported from PagerDuty, Opsgenie, ServiceNow, or internal systems.

Why use it

  • Track CFR and MTTR using production incidents
  • Link incidents directly to deployments
  • Use any incident-management system through the API

Where to configure it

Company Settings → Incident Detection

Read the Incidents API Guide →


4. Measurements v2 API

Measurements v2 lets you push custom time-series metrics into LinearB, including build times, error counts, performance KPIs, and pipeline statistics.

Common use cases

  • CI metrics such as build time, test duration, and success rate
  • Operational KPIs
  • Team-, service-, and organization-level signals

Read the Measurements v2 API Guide →


5. External Custom Metrics API

Send metrics from external tools and associate them directly with pull requests, repositories, commits, or contributors.

Examples

  • Code coverage per pull request
  • Security-scan results
  • CI job-level statistics

Read the External Custom Metrics Guide →


6. Services API

Define services and associate repositories so LinearB can:

  • Calculate DORA metrics by service
  • Filter deployments in monorepos
  • Attribute incidents correctly

Read the Services API Guide →


7. Teams v2 API

Automate team creation, team updates, and contributor membership across your organization.

Useful for

  • Organizations with HRIS-driven teams
  • Automated provisioning
  • Frequent organizational changes

Read the Teams v2 API Guide →


8. Users API

Provision, retrieve, update, and remove contributor identities.

Useful for

  • Identity synchronization
  • Contributor profile management
  • Email-alias management
  • Automated onboarding and offboarding

Offboarding and historical data

  • Use DELETE /api/v1/users/{user_id} when offboarding a former employee.
  • Deleting a user preserves their historical activity and existing metrics attribution.
  • Historical activity can be excluded from metrics separately when needed.
  • Deleted users can currently be restored through the LinearB UI. Restoration through the API is planned.
  • A user whose team_membership value is not null is billable.

Read the Users API Guide →

View the Users API Reference →


Troubleshooting Generic HTTP/API Errors

For job-specific issues, including jobs stuck in queued or running, see Tools and Utilities above.

401 Unauthorized or 403 Forbidden
  • API token missing or invalid
    — Check the API reference and confirm that the token is being sent in the required header.
    — Confirm that the token is active and has not been revoked.
  • Wrong organization or environment
    — Verify that the token belongs to the organization being queried and to the correct environment, such as production or staging.
  • Proxy or gateway stripping headers
    — If requests pass through a proxy, confirm that it preserves the authentication header.
404 Not Found
  • Incorrect URL
    — Check the base URL, API version, and path against the current API reference.
  • Missing or incorrect identifier
    — Confirm that the organization ID, deployment ID, service ID, job ID, or other resource identifier is correct and exists in LinearB.
  • Resource not yet created
    — Confirm that the resource was created successfully by checking the original POST response.
422 Invalid Payload
  • Invalid JSON
    — Validate the request body with a JSON validator.
    — Confirm that quotation marks, brackets, and commas are correct.
  • Missing required fields
    — Check the API reference and confirm that every required attribute is present, such as repo_url, ref_name, metric_name, or timestamp, where applicable.
  • Incorrect data types or formats
    — Verify field formats, including ISO 8601 timestamps such as 2024-01-03T10:15:30Z, and numeric versus string values.
429 Too Many Requests
  • You may be sending too many requests within a short period.
  • Implement retry logic with backoff and avoid tight polling loops.
  • If you consistently reach rate limits, contact your CSM to discuss available options.
5xx Server Errors
  • Temporary backend issue
    — Retry the request after a short delay.
  • Persistent 5xx responses
    — Capture the endpoint, full URL, timestamp, and correlation ID, if present, and share them with LinearB Support.

FAQs

Do I need a separate API token for each API?

No. A single token can be used across the supported API endpoints.

Can I rotate tokens without downtime?

Yes. Generate a new token, update your services to use it, verify that it works, and then revoke the old token.

Is there rate limiting?

Yes. Limits depend on request volume and endpoint type. If you reach a limit, retry with backoff.

Can I test requests before coding?

Yes. Use the API Test Client described above.

```

How did we do?

API - Deployment

Contact