API - Start Here

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

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.

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

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

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

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.

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.

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

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

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

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.

Troubleshooting Generic HTTP/API errors

FAQs