Skip to main content
Deutsch (Deutschland) Español Français Hebrew (Israel) Italiano Português

API - Start Here

Heather Hazell
Updated

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 (cycle time, activity, and more).
  • Services API — register or update services (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.

→ LinearB Public API Reference

Authentication & API Tokens

How Authentication Works

The LinearB API uses API tokens generated inside the LinearB app. All requests must include this token in the Authorization header.

Authorization: Bearer <your_api_token>

Your token determines:

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

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 time seeing the raw value.

Note: API tokens inherit your LinearB admin or editor privileges.

Securing Tokens

  • Rotate tokens regularly.
  • Store them in a vault (1Password, AWS Secrets Manager, Hashicorp Vault, etc.).
  • Revoke tokens immediately if exposed.

Tools & 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 – job is waiting to be processed
  • running – job is currently being processed
  • succeeded – job completed successfully
  • failed – 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 simple status indicator (for example, status: "ok").

API Test Client

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

  • Send authenticated GET/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 & Troubleshooting

Verify API health
  1. Send a request to the health endpoint (for example: GET /v1/health).
  2. Confirm you receive a 200 OK response.
  3. Review the response body for an overall status indicator (for example, 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 (for example: a bulk import or long-running API operation).
  2. From the response, copy the returned job_id.
  3. Poll the Job Status API (for example: GET /v1/jobs/{job_id}).
  4. Confirm the job transitions through states (for example: queued → running → succeeded or failed).

Quick fixes (most common issues)

  • Health check returns 401 or 403
    - Authentication or authorization is failing.
    - Confirm the x-api-key (or equivalent) is present, 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 your status page or contact your CSM/support.
  • Job stays in queued for too long
    - The worker queue may be busy or the job has not yet been picked up.
    - Compare 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 a long-running operation.
    - If it exceeds normal duration, capture the job_id and share it with support/your CSM for investigation.
  • Job status is failed
    - The job encountered a validation or processing error.
    - Inspect the job status response for an error message or code and correct the underlying issue (payload, configuration, or upstream system), then trigger a new job.

Advanced troubleshooting

Use this matrix when health checks or job status results still don’t match expectations.

Problem Cause Fix
Health endpoint returns 401 / 403

Authentication/authorization issue:

  • Missing or invalid API key
  • Key belongs to a different environment or organization
 Verify the x-api-key header is present and correct.
Confirm the key belongs to the org/environment you are monitoring.
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 your status page or contact your CSM/support with timestamps and any response details.
Job stuck in queued The job has not yet been picked up by a worker, often due to high load or many queued jobs. Wait a few minutes and poll again.
If the job remains queued for an unusually long time, capture the job_id, approximate start time, and share with support.
Job stuck in running The job is still processing, or an internal step is slow/blocked. Compare the runtime with similar jobs to understand typical duration.
If this job is an outlier, capture the job_id and context and contact support.
Job ends in failed The work submitted to the job hit a validation or processing error (for example, invalid payload, missing references, or upstream failure). Inspect the job status response for an error message or code.
Fix the underlying issue (payload fields, references, configuration), then start a new job and monitor its status.
Jobs succeed, but data seems missing

The job completed successfully, but:

  • The scope (time range, team, project) did not match what you expected, or
  • You are viewing dashboards with filters that exclude the processed data.
 Confirm what the job was configured to process (for example, specific time window or subset of entities).
Adjust dashboard/report filters to match that scope, or rerun a job with corrected parameters.

API Reference Articles

LinearB provides a collection of APIs to help you:

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

All APIs use bearer-token authentication:

Authorization: Bearer <your_api_token>

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

Click any section below to open its full guide:

  1. API Overview 

  2. Deployments API

  3. Incidents API

  4. Measurements v2 API

  5. External Custom Metrics API

  6. Services API

  7. Teams v2 API

  8. Users API
  

Troubleshooting Generic HTTP/API errors

p>For job-specific issues (jobs stuck in queued or running), see Tools & Utilities → Job Status & Health above.

 

401 Unauthorized
  • API token missing or invalid
    - Ensure you are sending the token in the correct header (for example: x-api-key).
    - Confirm the token is active and has not been revoked.
  • Wrong organization or environment
    - Verify the token belongs to the same organization you are querying (and to the correct env: prod vs. staging).
  • Proxy or gateway stripping headers
    - If calls go through a proxy, confirm it is not removing auth headers.
404 Not Found
  • Incorrect URL
    - Double-check the base URL, version (/v1 vs /v2), and path.
  • Missing or wrong identifier
    - Make sure the organization ID, deployment ID, service ID, job ID, etc. is correct and exists in LinearB.
  • Resource not yet created
    - Confirm that you successfully created the resource (check logs for the original POST response).
422 Invalid Payload
  • Invalid JSON
    - Validate your request body with a JSON validator.
    - Ensure quotes, brackets, and commas are correct.
  • Missing required fields
    - Check the API reference to confirm all required attributes are present (for example: repo_url, ref_name, metric_name, timestamp, etc.).
  • Wrong data types or formats
    - Verify field formats (for example: ISO 8601 timestamps like 2024-01-03T10:15:30Z, numeric vs. string values).
429 Too Many Requests
  • You may be sending too many requests in a short time window.
  • Implement retry logic with backoff and avoid tight polling loops.
  • If you consistently hit rate limits, contact your CSM to discuss 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 with support.

 

FAQs

Do I need a separate API token for each API?

No. A single token can be used for all API endpoints.

Can I rotate tokens without downtime?

Yes. Generate a new token, switch your services to use it, then revoke the old one.

Is there rate limiting?

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

Can I test requests before coding?

Yes — use the API Test Client (included above).

Related articles