openapi: 3.1.0
info:
  title: SonarQube Web 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
paths:
  /projects/search:
    get:
      operationId: searchProjects
      summary: Search Projects
      description: >-
        Search for projects and components on the SonarQube instance.
        Supports filtering by organization, quality gate, languages, tags,
        and analysis date. Returns paginated results with component details.
      tags:
        - Projects
      parameters:
        - name: q
          in: query
          description: Search query to filter projects by name or key
          schema:
            type: string
        - name: p
          in: query
          description: Page number (1-based)
          schema:
            type: integer
            default: 1
        - name: ps
          in: query
          description: Page size (max 500)
          schema:
            type: integer
            default: 100
        - name: filter
          in: query
          description: Filter string (e.g. alert_status=OK)
          schema:
            type: string
        - name: qualitygate
          in: query
          description: Filter by quality gate name
          schema:
            type: string
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved list of projects
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectSearchResponse'
        '401':
          description: Unauthorized
  /projects/create:
    post:
      operationId: createProject
      summary: Create Project
      description: >-
        Create a new project in SonarQube. Sets the project key, name,
        visibility (public/private), and optional quality profile associations.
      tags:
        - Projects
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: Project created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCreateResponse'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
  /projects/delete:
    post:
      operationId: deleteProject
      summary: Delete Project
      description: >-
        Delete a project and all its associated data including analysis
        history, issues, and quality gate status.
      tags:
        - Projects
      security:
        - basicAuth: []
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - project
              properties:
                project:
                  type: string
                  description: Project key
      responses:
        '204':
          description: Project deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /issues/search:
    get:
      operationId: searchIssues
      summary: Search Issues
      description: >-
        Search for code issues across projects. Supports filtering by
        severity, type, status, assignee, resolution, language, rule,
        tags, date ranges, and component scope.
      tags:
        - Issues
      parameters:
        - name: componentKeys
          in: query
          description: Comma-separated list of component keys to scope the search
          schema:
            type: string
        - name: severities
          in: query
          description: Comma-separated severities (INFO, MINOR, MAJOR, CRITICAL, BLOCKER)
          schema:
            type: string
        - name: types
          in: query
          description: Comma-separated issue types (CODE_SMELL, BUG, VULNERABILITY, SECURITY_HOTSPOT)
          schema:
            type: string
        - name: statuses
          in: query
          description: Comma-separated statuses (OPEN, CONFIRMED, REOPENED, RESOLVED, CLOSED)
          schema:
            type: string
        - name: resolved
          in: query
          description: Filter by resolution status
          schema:
            type: boolean
        - name: rules
          in: query
          description: Comma-separated rule keys
          schema:
            type: string
        - name: languages
          in: query
          description: Comma-separated language keys
          schema:
            type: string
        - name: p
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: ps
          in: query
          description: Page size (max 500)
          schema:
            type: integer
            default: 100
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved issues
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IssueSearchResponse'
        '401':
          description: Unauthorized
  /qualitygates/list:
    get:
      operationId: listQualityGates
      summary: List Quality Gates
      description: >-
        List all quality gates defined in the SonarQube instance.
        Quality gates define the conditions a project must meet to
        be considered production-ready.
      tags:
        - Quality Gates
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved quality gates
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityGateListResponse'
        '401':
          description: Unauthorized
  /qualitygates/project_status:
    get:
      operationId: getQualityGateStatus
      summary: Get Quality Gate Status
      description: >-
        Get the quality gate status for a specific project or analysis.
        Returns overall status (OK/ERROR) and individual condition results.
      tags:
        - Quality Gates
      parameters:
        - name: projectKey
          in: query
          description: Project key
          schema:
            type: string
        - name: analysisId
          in: query
          description: Analysis ID (alternative to projectKey)
          schema:
            type: string
        - name: branch
          in: query
          description: Branch name
          schema:
            type: string
        - name: pullRequest
          in: query
          description: Pull request identifier
          schema:
            type: string
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved quality gate status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QualityGateStatus'
        '401':
          description: Unauthorized
        '404':
          description: Project not found
  /measures/component:
    get:
      operationId: getComponentMeasures
      summary: Get Component Measures
      description: >-
        Get measures (metrics) for a specific component. Returns values
        for requested metric keys such as coverage, bugs, vulnerabilities,
        code smells, duplications, and lines of code.
      tags:
        - Measures
      parameters:
        - name: component
          in: query
          required: true
          description: Component key
          schema:
            type: string
        - name: metricKeys
          in: query
          required: true
          description: Comma-separated metric keys to retrieve
          schema:
            type: string
        - name: branch
          in: query
          description: Branch name
          schema:
            type: string
        - name: pullRequest
          in: query
          description: Pull request identifier
          schema:
            type: string
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved component measures
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComponentMeasuresResponse'
        '401':
          description: Unauthorized
        '404':
          description: Component not found
  /rules/search:
    get:
      operationId: searchRules
      summary: Search Rules
      description: >-
        Search for analysis rules available in SonarQube. Supports filtering
        by language, type, severity, quality profile, repository, and tags.
        Rules define the code quality and security checks performed during analysis.
      tags:
        - Rules
      parameters:
        - name: q
          in: query
          description: Search query for rule name or key
          schema:
            type: string
        - name: languages
          in: query
          description: Comma-separated language keys
          schema:
            type: string
        - name: types
          in: query
          description: Comma-separated rule types
          schema:
            type: string
        - name: severities
          in: query
          description: Comma-separated severities
          schema:
            type: string
        - name: repositories
          in: query
          description: Comma-separated rule repository keys
          schema:
            type: string
        - name: p
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: ps
          in: query
          description: Page size
          schema:
            type: integer
            default: 100
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved rules
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuleSearchResponse'
        '401':
          description: Unauthorized
  /users/search:
    get:
      operationId: searchUsers
      summary: Search Users
      description: >-
        Search for users in the SonarQube instance. Supports filtering by
        login, name, and group membership. Requires Administer System permission.
      tags:
        - Users
      parameters:
        - name: q
          in: query
          description: Search query to filter by login or name
          schema:
            type: string
        - name: p
          in: query
          description: Page number
          schema:
            type: integer
            default: 1
        - name: ps
          in: query
          description: Page size
          schema:
            type: integer
            default: 50
      security:
        - basicAuth: []
        - bearerAuth: []
      responses:
        '200':
          description: Successfully retrieved users
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserSearchResponse'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden - Insufficient permissions
  /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:
  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.
  schemas:
    ProjectSearchResponse:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        components:
          type: array
          items:
            $ref: '#/components/schemas/Project'
    Project:
      type: object
      properties:
        key:
          type: string
          description: Project key (unique identifier)
        name:
          type: string
          description: Project display name
        qualifier:
          type: string
          enum: [TRK, APP, VW]
          description: Component qualifier
        visibility:
          type: string
          enum: [public, private]
        lastAnalysisDate:
          type: string
          format: date-time
          description: Timestamp of the last analysis
        revision:
          type: string
          description: SCM revision of last analysis
        managed:
          type: boolean
          description: Whether the project is externally managed
    CreateProjectRequest:
      type: object
      required:
        - project
        - name
      properties:
        project:
          type: string
          description: Project key (unique, alphanumeric, dashes, underscores)
        name:
          type: string
          description: Project display name
        visibility:
          type: string
          enum: [public, private]
          description: Project visibility
        mainBranch:
          type: string
          description: Name of the main branch (default: main)
    ProjectCreateResponse:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Project'
    IssueSearchResponse:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        issues:
          type: array
          items:
            $ref: '#/components/schemas/Issue'
        components:
          type: array
          items:
            type: object
        rules:
          type: array
          items:
            type: object
    Issue:
      type: object
      properties:
        key:
          type: string
          description: Unique issue key
        rule:
          type: string
          description: Rule key that triggered the issue
        severity:
          type: string
          enum: [INFO, MINOR, MAJOR, CRITICAL, BLOCKER]
        component:
          type: string
          description: Component key where the issue was found
        project:
          type: string
          description: Project key
        line:
          type: integer
          description: Line number in the source file
        hash:
          type: string
          description: Issue hash for deduplication
        textRange:
          type: object
          properties:
            startLine:
              type: integer
            endLine:
              type: integer
            startOffset:
              type: integer
            endOffset:
              type: integer
        status:
          type: string
          enum: [OPEN, CONFIRMED, REOPENED, RESOLVED, CLOSED]
        resolution:
          type: string
          enum: [FIXED, FALSE-POSITIVE, WONTFIX, REMOVED]
        type:
          type: string
          enum: [CODE_SMELL, BUG, VULNERABILITY, SECURITY_HOTSPOT]
        message:
          type: string
          description: Issue description message
        author:
          type: string
          description: SCM author of the issue
        assignee:
          type: string
          description: Assigned user login
        creationDate:
          type: string
          format: date-time
        updateDate:
          type: string
          format: date-time
        tags:
          type: array
          items:
            type: string
        effort:
          type: string
          description: Remediation effort estimate (e.g., 5min)
        debt:
          type: string
          description: Technical debt amount
    QualityGateListResponse:
      type: object
      properties:
        qualitygates:
          type: array
          items:
            $ref: '#/components/schemas/QualityGate'
        default:
          type: integer
          description: ID of the default quality gate
    QualityGate:
      type: object
      properties:
        id:
          type: string
          description: Quality gate identifier
        name:
          type: string
          description: Quality gate name
        isDefault:
          type: boolean
        isBuiltIn:
          type: boolean
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/QualityGateCondition'
    QualityGateCondition:
      type: object
      properties:
        id:
          type: string
        metric:
          type: string
          description: Metric key for this condition
        op:
          type: string
          enum: [LT, GT]
          description: Comparison operator
        error:
          type: string
          description: Threshold value that causes ERROR status
    QualityGateStatus:
      type: object
      properties:
        projectStatus:
          type: object
          properties:
            status:
              type: string
              enum: [OK, ERROR, NONE]
            conditions:
              type: array
              items:
                type: object
                properties:
                  status:
                    type: string
                    enum: [OK, ERROR, NO_VALUE]
                  metricKey:
                    type: string
                  comparator:
                    type: string
                  errorThreshold:
                    type: string
                  actualValue:
                    type: string
            periods:
              type: array
              items:
                type: object
            ignoredConditions:
              type: boolean
    ComponentMeasuresResponse:
      type: object
      properties:
        component:
          type: object
          properties:
            key:
              type: string
            name:
              type: string
            description:
              type: string
            qualifier:
              type: string
            measures:
              type: array
              items:
                $ref: '#/components/schemas/Measure'
    Measure:
      type: object
      properties:
        metric:
          type: string
          description: Metric key (e.g., coverage, bugs, vulnerabilities)
        value:
          type: string
          description: Metric value
        bestValue:
          type: boolean
          description: Whether this value is the best possible for the metric
        period:
          type: object
          properties:
            index:
              type: integer
            value:
              type: string
            bestValue:
              type: boolean
    RuleSearchResponse:
      type: object
      properties:
        total:
          type: integer
        p:
          type: integer
        ps:
          type: integer
        rules:
          type: array
          items:
            $ref: '#/components/schemas/Rule'
    Rule:
      type: object
      properties:
        key:
          type: string
          description: Rule key (e.g., java:S1234)
        name:
          type: string
          description: Rule name
        status:
          type: string
          enum: [BETA, DEPRECATED, READY, REMOVED]
        lang:
          type: string
          description: Language key
        langName:
          type: string
          description: Language display name
        type:
          type: string
          enum: [CODE_SMELL, BUG, VULNERABILITY, SECURITY_HOTSPOT]
        severity:
          type: string
          enum: [INFO, MINOR, MAJOR, CRITICAL, BLOCKER]
        htmlDesc:
          type: string
          description: HTML description of the rule
        tags:
          type: array
          items:
            type: string
        repo:
          type: string
          description: Rule repository key
    UserSearchResponse:
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
    User:
      type: object
      properties:
        login:
          type: string
          description: User login (unique identifier)
        name:
          type: string
          description: Display name
        active:
          type: boolean
          description: Whether the account is active
        email:
          type: string
          description: Email address
        local:
          type: boolean
          description: Whether this is a local (non-LDAP/SSO) account
        externalIdentity:
          type: string
          description: Identity for external authentication providers
        externalProvider:
          type: string
          description: Authentication provider name
        groups:
          type: array
          items:
            type: string
    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]
    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
    Paging:
      type: object
      properties:
        pageIndex:
          type: integer
          description: Current page number
        pageSize:
          type: integer
          description: Number of items per page
        total:
          type: integer
          description: Total number of items
tags:
  - name: Issues
    description: Code issue search and management
  - name: Measures
    description: Component metrics and measurement data
  - name: Projects
    description: Project creation, search, and management
  - name: Quality Gates
    description: Quality gate configuration and status
  - name: Rules
    description: Analysis rule search and configuration
  - name: System
    description: SonarQube server status and health monitoring
  - name: Users
    description: User account management