openapi: 3.2.0
info:
  title: SonarQube Web System API
  description: The SonarQube Web API provides HTTP endpoints for programmatic interaction with SonarQube Server. It enables management of projects, quality gates, issues, rules, users, groups, permissions, and CI/CD integrations. The API uses token-based authentication and follows REST conventions. It powers the SonarQube web UI and is used for CI/CD integration, custom tooling, and third-party plugin development.
  version: 10.0.0
  contact:
    name: SonarSource
    url: https://community.sonarsource.com/
  license:
    name: GNU Lesser General Public License v3.0
    url: https://www.gnu.org/licenses/lgpl-3.0.html
servers:
- url: https://{sonarqubeHost}/api
  description: SonarQube Server
  variables:
    sonarqubeHost:
      default: sonarqube.example.com
      description: Hostname of your SonarQube instance
tags:
- name: System
  description: SonarQube server status and health monitoring
paths:
  /system/status:
    get:
      operationId: getSystemStatus
      summary: Get System Status
      description: Get the operational status of the SonarQube instance, including server version and whether the system is UP, DOWN, STARTING, RESTARTING, DB_MIGRATION_NEEDED, or DB_MIGRATION_RUNNING.
      tags:
      - System
      responses:
        '200':
          description: Successfully retrieved system status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStatus'
  /system/health:
    get:
      operationId: getSystemHealth
      summary: Get System Health
      description: Get the health status of the SonarQube cluster including each node's health, causes of issues, and overall cluster health. Requires system passcode or System Administration permission.
      tags:
      - System
      security:
      - basicAuth: []
      - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved system health
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemHealth'
        '401':
          description: Unauthorized
components:
  schemas:
    SystemHealth:
      type: object
      properties:
        health:
          type: string
          enum:
          - GREEN
          - YELLOW
          - RED
        causes:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
        nodes:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              type:
                type: string
                enum:
                - APPLICATION
                - SEARCH
              host:
                type: string
              port:
                type: integer
              startedAt:
                type: string
                format: date-time
              health:
                type: string
                enum:
                - GREEN
                - YELLOW
                - RED
              causes:
                type: array
                items:
                  type: object
    SystemStatus:
      type: object
      properties:
        id:
          type: string
          description: Server ID
        version:
          type: string
          description: SonarQube version
        status:
          type: string
          enum:
          - UP
          - DOWN
          - STARTING
          - RESTARTING
          - DB_MIGRATION_NEEDED
          - DB_MIGRATION_RUNNING
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Basic authentication using a user token as the username and an empty password. Generate tokens in User > My Account > Security.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication using a SonarQube user token.