Skip to main content
Table of Contents

API - Services

Use the Services API to define services and their associated repositories, so LinearB can correctly attribute metrics such as DORA, deployments, incidents, and custom measurements to the right servic…

heather.hazell
Updated by heather.hazell

Use the Services API to define services and their associated repositories, so LinearB can correctly attribute metrics such as DORA, deployments, incidents, and custom measurements to the right service boundaries.

TL;DR

  • Use POST /v2/services to create services that represent deployable units (e.g., checkout, billing, mobile).
  • Use GET /v2/services and GET /v2/services/{service_id} to list and inspect services.
  • Use PATCH /v2/services/{service_id} to update names, descriptions, repos, or to deactivate a service.
  • Reference services in Deployments, Incidents, and Measurements payloads to get per-service DORA, CFR, MTTR, and custom metrics.
  • Deactivating a service hides it from dashboards but does not delete historical data.

Overview

The Services API allows you to create, update, and manage services in your organization. A service is typically a deployable unit such as:

  • Backend microservices
  • Front-end applications
  • Libraries or shared components
  • Monorepo sub-services

Services define deployment boundaries and can be used for:

  • DORA metrics by service
  • Incident attribution
  • Custom measurements per service
  • Deployment filtering (deploy only “service A” in monorepos)

Before You Begin

Authentication Requirements

All requests require an API token.

  1. Go to Company Settings → API Tokens.
  2. Create or reuse an existing token.
  3. Include the token in the header:
Authorization: Bearer <your_api_token>
Why Create Services?
  • You want DORA metrics per service (e.g., Checkout, Billing, Mobile App).
  • You want deployment filtering — only mark PRs as deployed for a given service.
  • You want more accurate CFR & MTTR results tied to the correct backend/app.
  • You want to use Measurements v2 per service.
Fields You Can Define
  • service_id – auto-generated or provided.
  • name – display name.
  • description.
  • repositories – array of repo URLs or repo identifiers.
  • active – whether the service is enabled.

Create & Manage Services

1. Create a Service

Create a new service

Endpoint

POST /v2/services

Example request body

{
            "name": "checkout-service", 

            "description": "Handles payments and checkout flows", 

            "repositories": [ 

              "github.com/acme/checkout", 

              "github.com/acme/payments" 

            ] 

          }

2. List All Services

Retrieve all existing services

Endpoint

GET /v2/services

Response includes name, id, description, repo list, and active status.

3. Get a Single Service

Retrieve service by ID

Endpoint

GET /v2/services/{service_id}

4. Update a Service

Modify name, description, or repo list

Endpoint

PATCH /v2/services/{service_id}

Example request body

{
            "name": "checkout-api", 

            "repositories": [ 

              "github.com/acme/checkout" 

            ] 

          }

5. Deactivate a Service

Soft-delete by marking inactive

Endpoint

PATCH /v2/services/{service_id}

Example request body

{
            "active": false 

          }

How Services Are Used in LinearB

Deployment Filtering

When using the Deployments API, you may specify a service to control which PRs are evaluated for deployment.

Example deployment payload (excerpt)

{
            "ref_name": "v2.5.1", 

            "service": "checkout-service" 

          }

This prevents unrelated PRs in monorepos from being marked as deployed.

DORA Metrics by Service

Services allow teams to measure:

  • Deployment Frequency
  • Lead Time for Changes
  • CFR
  • MTTR
Incident Attribution

Incidents linked to a service will affect only that service’s CFR and MTTR.

Measurements v2

Custom measurements can target a service:

{
            "name": "p95_latency", 

            "value": 420, 

            "timestamp": "2024-10-01T12:00:00Z", 

            "service_id": "checkout-service" 

          }

Verify & Troubleshooting

Verify a new or updated service
  1. Create or update a service using the Services API (for example, POST /api/v1/services or PATCH /api/v1/services/{service_id}).
  2. Confirm you receive a 2xx response and that the response body includes the expected fields (name, key/identifier, repo mappings, etc.).
  3. Call GET /api/v1/services or GET /api/v1/services/{service_id} to verify that the service is returned as expected.
  4. In LinearB, check any views that use services (for example, incident mapping, deployment views, or service-level dashboards) to confirm the service appears and can be selected where applicable.
Quick fixes (most common issues)
  • Service not appearing in API results
    – Confirm the create request returned a 201 or 2xx status, not a 4xx or 5xx.
    – Check that required fields (such as service name and key/identifier) were provided.
    – Verify you’re querying with the correct filters (for example, not restricting by a different environment or org).
  • Service appears in API, but not in the LinearB UI
    – Some UI filters (environment, team, activity) may hide services that have no associated data yet.
    – The service may not be linked to any repositories, teams, or incidents/deployments.
  • Service not available as a filter for incidents/deployments
    – The service is not correctly mapped to repos/paths that your incidents and deployments touch.
    – The service identifier used in your Incidents/Deployments payload does not match the one defined in the Services API.
  • 422 validation errors when creating/updating services
    – Required fields missing (e.g., name or a unique service key).
    – Invalid field types or unsupported values in mapping definitions (repos/paths/tags).
  • 401 / 403 errors
    – x-api-key header missing, invalid, or belongs to a different organization.
    – The token does not have sufficient permissions for service management.
Advanced troubleshooting (problem → cause → fix)

Use this matrix when service records still don’t behave as expected.

Problem Cause Fix
Service not created The create request failed validation or authorization.
Common causes:
  • Missing name or unique identifier.
  • Invalid mapping definitions (e.g., invalid repo/path references).
  • Missing or invalid x-api-key.
 Check the HTTP status and error body (especially 400 / 422).
Fix the payload (or API key) and re-send the request.
Service created, but never used in metrics The service is not associated with the repos/paths where code changes, deployments, or incidents occur.
Or the mapping rules are too narrow and don’t match real-world activity. 		Review your service mappings (repos, directories, tags) via the Services API response.
Align them with how your teams actually structure their code and deployments, then re-check dashboards after new activity.
Incidents/deployments not linked to the service The service identifier used in Incidents/Deployments payloads doesn’t match the one defined in the Services API.
Or deployments/incidents are not touching code mapped to this service. 		Make sure the same service key/name is used consistently across:
  • Services API definitions
  • Deployment events
  • Incident events
Adjust either the API payloads or the service definition so they align.
Service appears multiple times (duplicates) Multiple services were created with overlapping names/keys or mappings that conceptually represent the same thing. Decide which service should be canonical.
Update your integrations to use a single service identifier and deprecate or remove duplicates where possible.
Updates to a service not reflected in UI The wrong service_id was used, or the update failed partially and the error was ignored.
In some cases, cached UI views might delay the visible change. 		Use GET /api/v1/services/{service_id} to verify the stored version of the service.
Confirm your update call returned 2xx and targeted the correct ID, then refresh the UI and re-check.

FAQ

Can a repo belong to multiple services?

Yes. This is common for monorepo setups.

Does deactivating a service delete data?

No — it simply hides it from dashboards.

Do services impact team metrics?

No — services are independent of contributor-based team structure.

What happens if a PR touches multiple services?

The PR may be associated with multiple services depending on your repo list and deployment filtering.

For additional information, please visit our external API documentation

For additional technical support, please contact LinearB support.

How did we do?

API - Measurements v2

API - Start Here

Contact