openapi: 3.2.0
info:
  title: Jenkins Pipeline Graph View Plugin Pipeline Overview API
  description: 'REST API for the Jenkins Pipeline Graph View Plugin. This plugin provides enhanced visualization

    and interaction capabilities for Jenkins pipeline builds.


    The plugin exposes two main sets of endpoints:

    - Pipeline Overview APIs: For individual pipeline run details, console output, and build control

    - Multi-Pipeline Graph APIs: For viewing multiple pipeline runs in aggregate'
  version: 1.0.0
  contact:
    name: Jenkins Pipeline Graph View Plugin
    url: https://github.com/jenkinsci/pipeline-graph-view-plugin
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
servers:
- url: '{build_url}/stages'
  description: Pipeline Overview API - Individual pipeline run
  variables:
    build_url:
      default: http://localhost:8080/jenkins/job/my-pipeline/1
      description: Complete build URL including Jenkins server, job path, and build number
- url: '{job_url}/multi-pipeline-graph'
  description: Multi-Pipeline Graph API - Multiple pipeline runs
  variables:
    job_url:
      default: http://localhost:8080/jenkins/job/my-pipeline
      description: Complete job URL including Jenkins server and job path
tags:
- name: Pipeline Overview
  description: APIs for individual pipeline run visualization and control
paths:
  /tree:
    get:
      tags:
      - Pipeline Overview
      summary: Get pipeline stage tree
      description: 'Returns the complete stage tree structure for the pipeline run, including all stages,

        their states, timing information, and hierarchy.'
      operationId: getPipelineTree
      responses:
        '200':
          description: Pipeline tree structure
          headers:
            Cache-Control:
              description: Cache control header - immutable if complete, no-store if running
              schema:
                type: string
                examples:
                - private, immutable, max-age=86400
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelineTreeResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /allSteps:
    get:
      tags:
      - Pipeline Overview
      summary: Get all pipeline steps
      description: 'Returns all steps across all stages in the pipeline run. This endpoint reduces

        the number of API calls needed by providing all step information at once.'
      operationId: getAllSteps
      responses:
        '200':
          description: All pipeline steps
          headers:
            Cache-Control:
              description: Cache control header - immutable if complete, no-store if running
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepListResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /steps:
    get:
      tags:
      - Pipeline Overview
      summary: Get steps for a specific node
      description: 'Returns steps for a specific stage or node. This is a legacy endpoint

        maintained for compatibility.'
      operationId: getStepsByNode
      parameters:
      - name: nodeId
        in: query
        required: true
        description: The ID of the stage/node to get steps for
        schema:
          type: string
      responses:
        '200':
          description: Steps for the specified node
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StepListResponse'
        '400':
          description: Missing or invalid nodeId parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /exceptionText:
    get:
      tags:
      - Pipeline Overview
      summary: Get exception text of a failed step
      description: Returns exception text of a specific failed step or stage.
      operationId: getExceptionText
      parameters:
      - name: nodeId
        in: query
        required: true
        description: The ID of the step/stage to get the exception text from
        schema:
          type: string
      responses:
        '200':
          description: Exception text
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Missing or invalid parameters
          content:
            text/plain:
              schema:
                type: string
  /log:
    get:
      tags:
      - Pipeline Overview
      summary: Get raw console text
      description: 'Returns raw console text for a step or stage. For stages, returns concatenated

        logs from all steps within the stage.'
      operationId: getConsoleText
      parameters:
      - name: nodeId
        in: query
        required: true
        description: The ID of the step/stage to get console text for
        schema:
          type: string
      responses:
        '200':
          description: Raw console text
          content:
            text/plain:
              schema:
                type: string
        '400':
          description: Missing nodeId parameter
  /consoleBuildOutput:
    get:
      tags:
      - Pipeline Overview
      summary: Get full build console output
      description: Returns the complete console output for the entire build in HTML format.
      operationId: getBuildConsoleOutput
      responses:
        '200':
          description: Full build console output in HTML
          content:
            text/html:
              schema:
                type: string
  /nextBuild:
    get:
      tags:
      - Pipeline Overview
      summary: Check for next build
      description: 'Checks if a build with the specified queue ID has started and returns

        its URL if available.'
      operationId: hasNextBuild
      parameters:
      - name: queueId
        in: query
        required: true
        description: Queue ID to check for started build
        schema:
          type: string
      responses:
        '200':
          description: Next build information (empty if not found)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NextBuildResponse'
        '400':
          description: Missing or invalid queueId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /doRerun:
    post:
      tags:
      - Pipeline Overview
      summary: Rerun the pipeline
      description: 'Reruns the pipeline using the Jenkins Replay Action feature with the same

        script and parameters.'
      operationId: rerunPipeline
      security:
      - jenkins_auth:
        - BUILD
      responses:
        '200':
          description: Rerun scheduled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RerunResponse'
        '403':
          description: Insufficient permissions
        '400':
          description: Build cannot be rerun (not buildable)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /doCancel:
    post:
      tags:
      - Pipeline Overview
      summary: Cancel the running pipeline
      description: Cancels the currently running pipeline build.
      operationId: cancelPipeline
      security:
      - jenkins_auth:
        - CANCEL
      responses:
        '200':
          description: Pipeline cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SuccessResponse'
        '403':
          description: Insufficient permissions
        '400':
          description: Pipeline cannot be cancelled (not running)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    RerunResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
        data:
          type: object
          properties:
            message:
              type: string
              description: Success message
            queueId:
              type: integer
              format: int64
              description: Queue ID of the scheduled rerun
    ErrorResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - error
        data:
          type: object
          properties:
            error:
              type: string
              description: Error message
    PipelineTreeResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
        data:
          $ref: '#/components/schemas/PipelineGraph'
    InputStep:
      type: object
      properties:
        message:
          type: string
          description: Input message displayed to user
        cancel:
          type: string
          description: Cancel button text
        id:
          type: string
          description: Input step ID
        ok:
          type: string
          description: OK button text
        parameters:
          type: boolean
          description: Whether the input step has parameters
    PipelineStage:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the stage
        name:
          type: string
          description: Display name of the stage
        state:
          $ref: '#/components/schemas/PipelineState'
        type:
          type: string
          description: Type of the stage (e.g., "STAGE", "PARALLEL")
        title:
          type: string
          description: Full title/description of the stage
        pauseDurationMillis:
          type: integer
          format: int64
          description: Duration in milliseconds the stage was paused
        startTimeMillis:
          type: integer
          format: int64
          description: Stage start time in milliseconds since epoch
        totalDurationMillis:
          types:
          - integer
          - null
          format: int64
          description: Total duration in milliseconds (null if still running)
        children:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStage'
          description: Child stages (for parallel or nested stages)
        seqContainerName:
          types:
          - string
          - null
          description: Name of sequential container if applicable
        nextSibling:
          types:
          - object
          - null
          $ref: '#/components/schemas/PipelineStage'
        isSequential:
          type: boolean
          description: Whether this stage is sequential
        synthetic:
          type: boolean
          description: Whether this is a synthetic stage
        placeholder:
          type: boolean
          description: Whether this is a placeholder stage
        agent:
          types:
          - string
          - null
          description: Agent information for the stage
        causeOfBlockage:
          types:
          - string
          - null
          description: Human-readable reason this stage is blocked. Currently set when the stage's state is "queued" because its `agent`/`node` step is waiting for an executor (e.g. "Waiting for next available executor on 'linux'"). Omitted when the stage is not blocked.
        url:
          type: string
          description: URL to view this stage in the UI
    StepList:
      type: object
      properties:
        steps:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStep'
        runIsComplete:
          type: boolean
          description: Whether the pipeline run is complete
    NextBuildResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
        data:
          type: object
          properties:
            nextBuildUrl:
              type: string
              description: URL of the next build (empty object if not found)
    StepListResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
        data:
          $ref: '#/components/schemas/StepList'
    PipelineGraph:
      type: object
      properties:
        complete:
          type: boolean
          description: Whether the pipeline run is complete
        stages:
          type: array
          items:
            $ref: '#/components/schemas/PipelineStage'
    SuccessResponse:
      type: object
      properties:
        status:
          type: string
          enum:
          - ok
        data:
          type: object
    PipelineState:
      type: string
      enum:
      - queued
      - running
      - paused
      - skipped
      - not_built
      - finished
      - success
      - unstable
      - failure
      - unknown
      - aborted
    PipelineStep:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the step
        name:
          type: string
          description: Display name of the step
        state:
          $ref: '#/components/schemas/PipelineState'
        type:
          type: string
          description: Type of the step
        title:
          type: string
          description: Full title/description of the step
        pauseDurationMillis:
          type: integer
          format: int64
          description: Duration in milliseconds the step was paused
        startTimeMillis:
          type: integer
          format: int64
          description: Step start time in milliseconds since epoch
        totalDurationMillis:
          types:
          - integer
          - null
          format: int64
          description: Total duration in milliseconds (null if still running)
        stageId:
          type: string
          description: ID of the parent stage
        inputStep:
          types:
          - object
          - null
          $ref: '#/components/schemas/InputStep'
  securitySchemes:
    jenkins_auth:
      type: http
      scheme: basic
      description: Jenkins basic authentication