openapi: 3.1.0
info:
  title: Apache Flink REST API
  description: >-
    The Flink REST API is exposed by the JobManager Dispatcher and provides
    monitoring and management capabilities for a Flink cluster. It covers
    cluster configuration, JobManager environment and metrics, job lifecycle
    (submit, list, cancel, stop), checkpoint and savepoint management, JAR
    upload and execution, dataset operations, and TaskManager inspection.
  version: v1
  contact:
    name: Apache Flink
    url: https://flink.apache.org/community/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
  - url: http://localhost:8081
    description: Default JobManager Dispatcher endpoint
tags:
  - name: Cluster
    description: Cluster lifecycle and configuration.
  - name: JobManager
    description: JobManager configuration, environment, logs, metrics, and threads.
  - name: Jobs
    description: Job lifecycle and inspection.
  - name: Checkpoints
    description: Checkpoint configuration, status, and details.
  - name: JARs
    description: JAR upload, listing, run, and delete.
  - name: TaskManagers
    description: TaskManager listing and inspection.
  - name: Datasets
    description: Cluster dataset listing and deletion.
paths:
  /cluster:
    delete:
      tags:
        - Cluster
      summary: Shut down the cluster
      operationId: shutdownCluster
      responses:
        '200':
          description: Cluster shutdown initiated.
  /config:
    get:
      tags:
        - Cluster
      summary: Web UI configuration
      operationId: getWebUIConfig
      responses:
        '200':
          description: Web UI configuration.
  /jobmanager/config:
    get:
      tags:
        - JobManager
      summary: Cluster configuration
      operationId: getJobManagerConfig
      responses:
        '200':
          description: JobManager configuration entries.
  /jobmanager/environment:
    get:
      tags:
        - JobManager
      summary: JobManager environment
      operationId: getJobManagerEnvironment
      responses:
        '200':
          description: JobManager JVM and environment details.
  /jobmanager/logs:
    get:
      tags:
        - JobManager
      summary: List JobManager log files
      operationId: listJobManagerLogs
      responses:
        '200':
          description: Available JobManager log files.
  /jobmanager/metrics:
    get:
      tags:
        - JobManager
      summary: JobManager metrics
      operationId: getJobManagerMetrics
      parameters:
        - in: query
          name: get
          schema:
            type: string
          description: Comma-separated metric names.
      responses:
        '200':
          description: Requested JobManager metric values.
  /jobmanager/thread-dump:
    get:
      tags:
        - JobManager
      summary: JobManager thread dump
      operationId: getJobManagerThreadDump
      responses:
        '200':
          description: Thread dump of the JobManager.
  /jobs:
    get:
      tags:
        - Jobs
      summary: List jobs
      operationId: listJobs
      responses:
        '200':
          description: List of jobs and their status.
  /jobs/overview:
    get:
      tags:
        - Jobs
      summary: Jobs overview
      operationId: getJobsOverview
      responses:
        '200':
          description: Overview of all jobs.
  /jobs/metrics:
    get:
      tags:
        - Jobs
      summary: Aggregated job metrics
      operationId: getJobsMetrics
      responses:
        '200':
          description: Aggregated job-level metrics.
  /jobs/{jobid}:
    get:
      tags:
        - Jobs
      summary: Get job details
      operationId: getJob
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Details of the specified job.
    patch:
      tags:
        - Jobs
      summary: Cancel or stop a job
      operationId: terminateJob
      parameters:
        - $ref: '#/components/parameters/JobId'
        - in: query
          name: mode
          schema:
            type: string
            enum: [cancel, stop]
      responses:
        '202':
          description: Termination accepted.
  /jobs/{jobid}/config:
    get:
      tags:
        - Jobs
      summary: Job configuration
      operationId: getJobConfig
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Job configuration values.
  /jobs/{jobid}/exceptions:
    get:
      tags:
        - Jobs
      summary: Job exception history
      operationId: getJobExceptions
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Recorded exceptions for the job.
  /jobs/{jobid}/accumulators:
    get:
      tags:
        - Jobs
      summary: Job accumulators
      operationId: getJobAccumulators
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Accumulator values for the job.
  /jobs/{jobid}/checkpoints:
    get:
      tags:
        - Checkpoints
      summary: Checkpoint statistics for a job
      operationId: getJobCheckpoints
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Aggregated checkpoint information.
    post:
      tags:
        - Checkpoints
      summary: Trigger a checkpoint
      operationId: triggerCheckpoint
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '202':
          description: Checkpoint trigger accepted.
  /jobs/{jobid}/checkpoints/config:
    get:
      tags:
        - Checkpoints
      summary: Checkpoint configuration for a job
      operationId: getCheckpointConfig
      parameters:
        - $ref: '#/components/parameters/JobId'
      responses:
        '200':
          description: Checkpointing configuration.
  /jobs/{jobid}/checkpoints/details/{checkpointid}:
    get:
      tags:
        - Checkpoints
      summary: Checkpoint details
      operationId: getCheckpointDetails
      parameters:
        - $ref: '#/components/parameters/JobId'
        - in: path
          name: checkpointid
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Detailed information for a single checkpoint.
  /jars:
    get:
      tags:
        - JARs
      summary: List uploaded JARs
      operationId: listJars
      responses:
        '200':
          description: Uploaded JARs available for execution.
  /jars/upload:
    post:
      tags:
        - JARs
      summary: Upload a JAR
      operationId: uploadJar
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                jarfile:
                  type: string
                  format: binary
      responses:
        '200':
          description: JAR uploaded successfully.
  /jars/{jarid}:
    delete:
      tags:
        - JARs
      summary: Delete a JAR
      operationId: deleteJar
      parameters:
        - in: path
          name: jarid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: JAR deleted.
  /jars/{jarid}/plan:
    get:
      tags:
        - JARs
      summary: Plan for a JAR
      operationId: getJarPlan
      parameters:
        - in: path
          name: jarid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dataflow plan for the JAR.
  /jars/{jarid}/run:
    post:
      tags:
        - JARs
      summary: Run a job from a JAR
      operationId: runJar
      parameters:
        - in: path
          name: jarid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job submitted from the JAR.
  /taskmanagers:
    get:
      tags:
        - TaskManagers
      summary: List TaskManagers
      operationId: listTaskManagers
      responses:
        '200':
          description: List of TaskManagers in the cluster.
  /taskmanagers/{taskmanagerid}/metrics:
    get:
      tags:
        - TaskManagers
      summary: TaskManager metrics
      operationId: getTaskManagerMetrics
      parameters:
        - in: path
          name: taskmanagerid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: TaskManager metrics.
  /taskmanagers/{taskmanagerid}/logs:
    get:
      tags:
        - TaskManagers
      summary: List TaskManager logs
      operationId: listTaskManagerLogs
      parameters:
        - in: path
          name: taskmanagerid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Available TaskManager log files.
  /datasets:
    get:
      tags:
        - Datasets
      summary: List cluster datasets
      operationId: listDatasets
      responses:
        '200':
          description: Available cluster datasets.
  /datasets/{datasetid}:
    delete:
      tags:
        - Datasets
      summary: Delete a cluster dataset
      operationId: deleteDataset
      parameters:
        - in: path
          name: datasetid
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Dataset deleted.
components:
  parameters:
    JobId:
      in: path
      name: jobid
      required: true
      schema:
        type: string
      description: A Flink job ID.