openapi: 3.0.1
info:
  title: LinearB Public API
  description: >-
    The LinearB public REST API for software engineering intelligence. Report
    deployments, push and update incidents, export engineering measurements
    (DORA and developer-productivity metrics), and manage teams and services.
    All requests are authenticated with an API token passed in the x-api-key
    request header.
  termsOfService: https://linearb.io/legal/terms-of-service
  contact:
    name: LinearB Support
    url: https://docs.linearb.io/api-overview/
  version: '1.0'
servers:
  - url: https://public-api.linearb.io
security:
  - apiKeyAuth: []
paths:
  /api/v1/deployments:
    post:
      operationId: createDeployment
      tags:
        - Deployments
      summary: Report a deployment.
      description: Reports a deployment so LinearB can calculate deployment frequency and lead time.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDeploymentRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateDeploymentResponse'
    get:
      operationId: listDeployments
      tags:
        - Deployments
      summary: List deployments.
      description: Returns a paginated list of reported deployments.
      parameters:
        - name: repository_id
          in: query
          schema:
            type: integer
        - name: after
          in: query
          schema:
            type: string
            format: date-time
        - name: before
          in: query
          schema:
            type: string
            format: date-time
        - name: stage
          in: query
          schema:
            type: string
        - name: commit_sha
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
        - name: offset
          in: query
          schema:
            type: string
        - name: sort_by
          in: query
          schema:
            type: string
            default: published_at
        - name: sort_dir
          in: query
          schema:
            type: string
            enum: [asc, desc]
            default: desc
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeploymentList'
  /api/v1/incidents:
    post:
      operationId: createIncident
      tags:
        - Incidents
      summary: Create an incident.
      description: Uploads a custom incident report to feed change failure rate and MTTR metrics.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateIncidentRequest'
      responses:
        '200':
          description: OK
  /api/v1/incidents/{provider_id}:
    patch:
      operationId: updateIncident
      tags:
        - Incidents
      summary: Update an incident.
      description: Updates an existing incident identified by its provider id.
      parameters:
        - name: provider_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateIncidentRequest'
      responses:
        '200':
          description: OK
  /api/v2/measurements:
    post:
      operationId: getMeasurements
      tags:
        - Measurements
      summary: Retrieve engineering metrics.
      description: >-
        Returns engineering metrics for the requested time ranges, grouping,
        and roll-up. Supported metrics may be aggregated (p50, p75, average).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementsRequest'
      responses:
        '200':
          description: OK
  /api/v2/measurements/export:
    post:
      operationId: exportMeasurements
      tags:
        - Measurements
      summary: Export engineering metrics.
      description: Generates a metrics report and drops it as a CSV or JSON file in cloud storage.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MeasurementsRequest'
      responses:
        '200':
          description: OK
  /api/v2/teams:
    get:
      operationId: searchTeams
      tags:
        - Teams
      summary: Search teams.
      responses:
        '200':
          description: OK
    post:
      operationId: createTeams
      tags:
        - Teams
      summary: Create teams.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTeamsRequest'
      responses:
        '200':
          description: OK
  /api/v2/teams/{team_id}:
    patch:
      operationId: updateTeam
      tags:
        - Teams
      summary: Update a team.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Team'
      responses:
        '200':
          description: OK
    delete:
      operationId: deleteTeam
      tags:
        - Teams
      summary: Delete a team.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
  /api/v2/teams/{team_id}/members:
    get:
      operationId: getTeamMembers
      tags:
        - Teams
      summary: Get team members.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
    post:
      operationId: setTeamMembers
      tags:
        - Teams
      summary: Set team members.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
    patch:
      operationId: addTeamMembers
      tags:
        - Teams
      summary: Add members to a team.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
  /api/v2/teams/{team_id}/members/{user_id_or_email}:
    delete:
      operationId: removeTeamMember
      tags:
        - Teams
      summary: Remove a member from a team.
      parameters:
        - name: team_id
          in: path
          required: true
          schema:
            type: integer
        - name: user_id_or_email
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
  /api/v1/services:
    get:
      operationId: listServices
      tags:
        - Services
      summary: List services.
      responses:
        '200':
          description: OK
    post:
      operationId: createServices
      tags:
        - Services
      summary: Create services.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateServicesRequest'
      responses:
        '200':
          description: OK
  /api/v1/services/{service_id}:
    get:
      operationId: getService
      tags:
        - Services
      summary: Get a service.
      parameters:
        - name: service_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
    put:
      operationId: updateService
      tags:
        - Services
      summary: Update a service.
      parameters:
        - name: service_id
          in: path
          required: true
          schema:
            type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Service'
      responses:
        '200':
          description: OK
    delete:
      operationId: deleteService
      tags:
        - Services
      summary: Delete a service.
      parameters:
        - name: service_id
          in: path
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: OK
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
  schemas:
    CreateDeploymentRequest:
      type: object
      required:
        - repo_url
        - ref_name
      properties:
        repo_url:
          type: string
          description: The git repository url.
        ref_name:
          type: string
          description: Ref name of the release, accepts any Git ref.
        timestamp:
          type: string
          format: date-time
          description: Deployment time in ISO 8601 format.
        stage:
          type: string
          description: The key of the custom pre-deployment stage (lowercase).
        services:
          type: array
          description: The list of LinearB service names (lowercase).
          items:
            type: string
    CreateDeploymentResponse:
      type: object
      properties:
        request_id:
          type: string
    DeploymentList:
      type: object
      properties:
        total:
          type: integer
        items:
          type: array
          items:
            $ref: '#/components/schemas/Deployment'
    Deployment:
      type: object
      properties:
        repository_id:
          type: integer
        ref_name:
          type: string
        commit_sha:
          type: string
        stage:
          type: string
        published_at:
          type: string
          format: date-time
    CreateIncidentRequest:
      type: object
      required:
        - provider_id
        - http_url
        - title
        - issued_at
      properties:
        provider_id:
          type: string
          description: Unique identifier of the incident in your incident management provider.
        http_url:
          type: string
          description: The URL of your incident management provider.
        title:
          type: string
          description: The title of the incident.
        issued_at:
          type: string
          format: date-time
          description: When the incident was logged and officially opened.
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        git_ref:
          type: string
        teams:
          type: array
          items:
            type: string
        services:
          type: array
          items:
            type: string
        repository_urls:
          type: array
          items:
            type: string
    UpdateIncidentRequest:
      type: object
      required:
        - title
        - issued_at
        - git_ref
      properties:
        title:
          type: string
        issued_at:
          type: string
          format: date-time
        git_ref:
          type: string
        started_at:
          type: string
          format: date-time
        ended_at:
          type: string
          format: date-time
        teams:
          type: array
          items:
            type: string
        services:
          type: array
          items:
            type: string
        repository_urls:
          type: array
          items:
            type: string
    MeasurementsRequest:
      type: object
      required:
        - requested_metrics
        - time_ranges
      properties:
        group_by:
          type: string
          description: Dimension to group results by (for example organization, team, repository, or contributor).
        roll_up:
          type: string
          description: Time aggregation granularity (for example 1d, 1w, 1mo, or custom).
          enum: [1d, 1w, 1mo, custom]
        requested_metrics:
          type: array
          description: The list of metrics to retrieve, optionally with an aggregation.
          items:
            $ref: '#/components/schemas/RequestedMetric'
        time_ranges:
          type: array
          description: One or more date ranges in yyyy-mm-dd format; multiple ranges require roll_up=custom.
          items:
            $ref: '#/components/schemas/TimeRange'
    RequestedMetric:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The metric key (for example branch.computed.cycle_time).
        agg:
          type: string
          description: Aggregation method for metrics that support it.
          enum: [p50, p75, avg, default]
    TimeRange:
      type: object
      required:
        - after
        - before
      properties:
        after:
          type: string
          description: Range start in yyyy-mm-dd format.
        before:
          type: string
          description: Range end in yyyy-mm-dd format, greater than after.
    CreateTeamsRequest:
      type: object
      properties:
        teams:
          type: array
          items:
            $ref: '#/components/schemas/Team'
    Team:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Team name, 3-100 characters beginning with a letter.
        parent_team:
          type: string
          description: Name of an existing parent team for hierarchy.
        initials:
          type: string
          description: Optional 1-3 character abbreviation.
        color:
          type: string
          description: Hex color code in #RGB or #RRGGBB format.
          default: '#348B83'
    CreateServicesRequest:
      type: object
      properties:
        services:
          type: array
          items:
            $ref: '#/components/schemas/Service'
    Service:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The service display name.
        repositories:
          type: array
          items:
            $ref: '#/components/schemas/ServiceRepository'
    ServiceRepository:
      type: object
      properties:
        url:
          type: string
          description: The repository URL.
        paths:
          type: array
          description: Directory paths within the repository belonging to this service.
          items:
            type: string