cc-backend/api/swagger.yaml

definitions:
  api.APIReturnedUser:
    properties:
      email:
        type: string
      name:
        type: string
      projects:
        items:
          type: string
        type: array
      roles:
        items:
          type: string
        type: array
      username:
        type: string
    type: object
  api.APITag:
    properties:
      name:
        description: Tag Name
        example: Testjob
        type: string
      scope:
        description: Tag Scope for Frontend Display
        example: global
        type: string
      type:
        description: Tag Type
        example: Debug
        type: string
    type: object
  api.DefaultAPIResponse:
    properties:
      msg:
        type: string
    type: object
  api.DeleteJobAPIRequest:
    properties:
      cluster:
        description: Cluster of job
        example: fritz
        type: string
      jobId:
        description: Cluster Job ID of job
        example: 123000
        type: integer
      startTime:
        description: Start Time of job as epoch
        example: 1649723812
        type: integer
    required:
    - jobId
    type: object
  api.EditMetaRequest:
    properties:
      key:
        example: jobScript
        type: string
      value:
        example: bash script
        type: string
    type: object
  api.ErrorResponse:
    properties:
      error:
        description: Error Message
        type: string
      status:
        description: Statustext of Errorcode
        type: string
    type: object
  api.GetClustersAPIResponse:
    properties:
      clusters:
        description: Array of clusters
        items:
          $ref: '#/definitions/schema.Cluster'
        type: array
    type: object
  api.GetJobAPIResponse:
    properties:
      data:
        items:
          $ref: '#/definitions/api.JobMetricWithName'
        type: array
      meta:
        $ref: '#/definitions/schema.Job'
    type: object
  api.GetJobsAPIResponse:
    properties:
      items:
        description: Number of jobs returned
        type: integer
      jobs:
        description: Array of jobs
        items:
          $ref: '#/definitions/schema.Job'
        type: array
      page:
        description: Page id returned
        type: integer
    type: object
  api.JobMetricWithName:
    properties:
      metric:
        $ref: '#/definitions/schema.JobMetric'
      name:
        type: string
      scope:
        $ref: '#/definitions/schema.MetricScope'
    type: object
  api.StopJobAPIRequest:
    properties:
      cluster:
        example: fritz
        type: string
      jobId:
        example: 123000
        type: integer
      jobState:
        allOf:
        - $ref: '#/definitions/schema.JobState'
        example: completed
      startTime:
        example: 1649723812
        type: integer
      stopTime:
        example: 1649763839
        type: integer
    required:
    - jobState
    - stopTime
    type: object
  api.UpdateNodeStatesRequest:
    properties:
      cluster:
        example: fritz
        type: string
      nodes:
        items:
          $ref: '#/definitions/schema.NodePayload'
        type: array
    type: object
  schema.Accelerator:
    properties:
      id:
        description: Unique identifier for the accelerator (e.g., "0", "1", "GPU-0")
        type: string
      model:
        description: Specific model name (e.g., "A100", "MI100")
        type: string
      type:
        description: Type of accelerator (e.g., "Nvidia GPU", "AMD GPU")
        type: string
    type: object
  schema.Cluster:
    properties:
      metricConfig:
        description: Cluster-wide metric configurations
        items:
          $ref: '#/definitions/schema.MetricConfig'
        type: array
      name:
        description: Unique cluster name (e.g., "fritz", "alex")
        type: string
      subClusters:
        description: Homogeneous partitions within the cluster
        items:
          $ref: '#/definitions/schema.SubCluster'
        type: array
    type: object
  schema.Job:
    description: Information of a HPC job.
    properties:
      arrayJobId:
        example: 123000
        type: integer
      cluster:
        example: fritz
        type: string
      concurrentJobs:
        $ref: '#/definitions/schema.JobLinkResultList'
      duration:
        example: 43200
        minimum: 1
        type: integer
      energy:
        type: number
      energyFootprint:
        additionalProperties:
          format: float64
          type: number
        type: object
      exclusive:
        description: for backwards compatibility
        example: 1
        maximum: 2
        minimum: 0
        type: integer
      footprint:
        additionalProperties:
          format: float64
          type: number
        type: object
      id:
        type: integer
      jobId:
        example: 123000
        type: integer
      jobState:
        allOf:
        - $ref: '#/definitions/schema.JobState'
        enum:
        - boot_fail
        - cancelled
        - completed
        - deadline
        - failed
        - node_fail
        - out-of-memory
        - pending
        - preempted
        - running
        - suspended
        - timeout
        example: completed
      metaData:
        additionalProperties:
          type: string
        type: object
      monitoringStatus:
        example: 1
        maximum: 3
        minimum: 0
        type: integer
      numAcc:
        example: 2
        minimum: 1
        type: integer
      numHwthreads:
        example: 20
        minimum: 1
        type: integer
      numNodes:
        example: 2
        minimum: 1
        type: integer
      partition:
        example: main
        type: string
      project:
        example: abcd200
        type: string
      requestedMemory:
        description: in MB
        example: 128000
        minimum: 1
        type: integer
      resources:
        items:
          $ref: '#/definitions/schema.Resource'
        type: array
      shared:
        enum:
        - none
        - single_user
        - multi_user
        type: string
      smt:
        example: 4
        type: integer
      startTime:
        example: 1649723812
        type: integer
      statistics:
        additionalProperties:
          $ref: '#/definitions/schema.JobStatistics'
        type: object
      subCluster:
        example: main
        type: string
      submitTime:
        example: 1649723812
        type: integer
      tags:
        items:
          $ref: '#/definitions/schema.Tag'
        type: array
      user:
        example: abcd100h
        type: string
      walltime:
        example: 86400
        minimum: 1
        type: integer
    type: object
  schema.JobLink:
    properties:
      id:
        description: Internal database ID
        type: integer
      jobId:
        description: The job's external job ID
        type: integer
    type: object
  schema.JobLinkResultList:
    properties:
      count:
        description: Total count of available items
        type: integer
      items:
        description: List of job links
        items:
          $ref: '#/definitions/schema.JobLink'
        type: array
    type: object
  schema.JobMetric:
    properties:
      series:
        description: Individual time series data
        items:
          $ref: '#/definitions/schema.Series'
        type: array
      statisticsSeries:
        allOf:
        - $ref: '#/definitions/schema.StatsSeries'
        description: Aggregated statistics over time
      timestep:
        description: Sampling interval in seconds
        type: integer
      unit:
        allOf:
        - $ref: '#/definitions/schema.Unit'
        description: Unit of measurement
    type: object
  schema.JobState:
    enum:
    - boot_fail
    - cancelled
    - completed
    - deadline
    - failed
    - node_fail
    - out_of_memory
    - pending
    - preempted
    - running
    - suspended
    - timeout
    type: string
    x-enum-varnames:
    - JobStateBootFail
    - JobStateCancelled
    - JobStateCompleted
    - JobStateDeadline
    - JobStateFailed
    - JobStateNodeFail
    - JobStateOutOfMemory
    - JobStatePending
    - JobStatePreempted
    - JobStateRunning
    - JobStateSuspended
    - JobStateTimeout
  schema.JobStatistics:
    description: Specification for job metric statistics.
    properties:
      avg:
        description: Job metric average
        example: 2500
        minimum: 0
        type: number
      max:
        description: Job metric maximum
        example: 3000
        minimum: 0
        type: number
      min:
        description: Job metric minimum
        example: 2000
        minimum: 0
        type: number
      unit:
        $ref: '#/definitions/schema.Unit'
    type: object
  schema.MetricConfig:
    properties:
      aggregation:
        description: Aggregation function (avg, sum, min, max)
        type: string
      alert:
        description: Alert threshold (requires attention)
        type: number
      caution:
        description: Caution threshold (concerning but not critical)
        type: number
      energy:
        description: Energy measurement method
        type: string
      footprint:
        description: Footprint category
        type: string
      lowerIsBetter:
        description: Whether lower values are better
        type: boolean
      name:
        description: Metric name (e.g., "cpu_load", "mem_used")
        type: string
      normal:
        description: Normal/typical value (good performance)
        type: number
      peak:
        description: Peak/maximum expected value (best performance)
        type: number
      restrict:
        description: Restrict visibility to non user roles
        type: boolean
      scope:
        allOf:
        - $ref: '#/definitions/schema.MetricScope'
        description: Metric scope (node, socket, core, etc.)
      subClusters:
        description: Subcluster-specific overrides
        items:
          $ref: '#/definitions/schema.SubClusterConfig'
        type: array
      timestep:
        description: Measurement interval in seconds
        type: integer
      unit:
        allOf:
        - $ref: '#/definitions/schema.Unit'
        description: Unit of measurement
    type: object
  schema.MetricScope:
    enum:
    - invalid_scope
    - node
    - socket
    - memoryDomain
    - core
    - hwthread
    - accelerator
    type: string
    x-enum-varnames:
    - MetricScopeInvalid
    - MetricScopeNode
    - MetricScopeSocket
    - MetricScopeMemoryDomain
    - MetricScopeCore
    - MetricScopeHWThread
    - MetricScopeAccelerator
  schema.MetricStatistics:
    properties:
      avg:
        description: Average/mean value
        type: number
      max:
        description: Maximum value
        type: number
      min:
        description: Minimum value
        type: number
    type: object
  schema.MetricValue:
    properties:
      unit:
        allOf:
        - $ref: '#/definitions/schema.Unit'
        description: Unit of measurement (e.g., FLOP/s, GB/s)
      value:
        description: Numeric value of the measurement
        type: number
    type: object
  schema.NodePayload:
    properties:
      cpusAllocated:
        description: Number of allocated CPUs
        type: integer
      gpusAllocated:
        description: Number of allocated GPUs
        type: integer
      hostname:
        description: Node hostname
        type: string
      jobsRunning:
        description: Number of running jobs
        type: integer
      memoryAllocated:
        description: Allocated memory in MB
        type: integer
      states:
        description: State strings (flexible format)
        items:
          type: string
        type: array
    type: object
  schema.Resource:
    description: A resource used by a job
    properties:
      accelerators:
        description: Allocated accelerator IDs (e.g., GPU IDs)
        items:
          type: string
        type: array
      configuration:
        description: Optional configuration identifier
        type: string
      hostname:
        description: Node hostname
        type: string
      hwthreads:
        description: Allocated hardware thread IDs
        items:
          type: integer
        type: array
    type: object
  schema.Series:
    properties:
      data:
        description: Time series measurements
        items:
          type: number
        type: array
      hostname:
        description: Source hostname
        type: string
      id:
        description: Optional ID (e.g., core ID, GPU ID)
        type: string
      statistics:
        allOf:
        - $ref: '#/definitions/schema.MetricStatistics'
        description: Statistical summary (min/avg/max)
    type: object
  schema.StatsSeries:
    properties:
      max:
        description: Maximum values over time
        items:
          type: number
        type: array
      mean:
        description: Mean values over time
        items:
          type: number
        type: array
      median:
        description: Median values over time
        items:
          type: number
        type: array
      min:
        description: Minimum values over time
        items:
          type: number
        type: array
      percentiles:
        additionalProperties:
          items:
            format: float64
            type: number
          type: array
        description: Percentile values over time (e.g., 10th, 50th, 90th)
        type: object
    type: object
  schema.SubCluster:
    properties:
      coresPerSocket:
        description: Number of cores per CPU socket
        type: integer
      energyFootprint:
        description: Energy-related footprint metrics
        items:
          type: string
        type: array
      flopRateScalar:
        allOf:
        - $ref: '#/definitions/schema.MetricValue'
        description: Theoretical scalar FLOP rate per node
      flopRateSimd:
        allOf:
        - $ref: '#/definitions/schema.MetricValue'
        description: Theoretical SIMD FLOP rate per node
      footprint:
        description: Default footprint metrics for jobs
        items:
          type: string
        type: array
      memoryBandwidth:
        allOf:
        - $ref: '#/definitions/schema.MetricValue'
        description: Theoretical memory bandwidth per node
      metricConfig:
        description: Subcluster-specific metric configurations
        items:
          $ref: '#/definitions/schema.MetricConfig'
        type: array
      name:
        description: Name of the subcluster (e.g., "main", "gpu", "bigmem")
        type: string
      nodes:
        description: Node list in condensed format (e.g., "node[001-100]")
        type: string
      processorType:
        description: CPU model (e.g., "Intel Xeon Gold 6148")
        type: string
      socketsPerNode:
        description: Number of CPU sockets per node
        type: integer
      threadsPerCore:
        description: Number of hardware threads per core (SMT level)
        type: integer
      topology:
        allOf:
        - $ref: '#/definitions/schema.Topology'
        description: Hardware topology of nodes in this subcluster
    type: object
  schema.SubClusterConfig:
    properties:
      alert:
        description: Alert threshold (requires attention)
        type: number
      caution:
        description: Caution threshold (concerning but not critical)
        type: number
      energy:
        description: Energy measurement configuration
        type: string
      footprint:
        description: Footprint category for this metric
        type: string
      lowerIsBetter:
        description: Whether lower values indicate better performance
        type: boolean
      name:
        description: Metric name (e.g., "cpu_load", "mem_used")
        type: string
      normal:
        description: Normal/typical value (good performance)
        type: number
      peak:
        description: Peak/maximum expected value (best performance)
        type: number
      remove:
        description: Whether to exclude this metric for this subcluster
        type: boolean
      restrict:
        description: Restrict visibility to non user roles
        type: boolean
      unit:
        allOf:
        - $ref: '#/definitions/schema.Unit'
        description: Unit of measurement
    type: object
  schema.Tag:
    description: Defines a tag using name and type.
    properties:
      id:
        type: integer
      name:
        example: Testjob
        type: string
      scope:
        example: global
        type: string
      type:
        example: Debug
        type: string
    type: object
  schema.Topology:
    properties:
      accelerators:
        description: Attached accelerators (GPUs, etc.)
        items:
          $ref: '#/definitions/schema.Accelerator'
        type: array
      core:
        description: Hardware threads grouped by core
        items:
          items:
            type: integer
          type: array
        type: array
      die:
        description: Hardware threads grouped by die (optional)
        items:
          items:
            type: integer
          type: array
        type: array
      memoryDomain:
        description: Hardware threads grouped by NUMA domain
        items:
          items:
            type: integer
          type: array
        type: array
      node:
        description: All hardware thread IDs on this node
        items:
          type: integer
        type: array
      socket:
        description: Hardware threads grouped by socket
        items:
          items:
            type: integer
          type: array
        type: array
    type: object
  schema.Unit:
    properties:
      base:
        description: Base unit (e.g., "B/s", "F/s", "W")
        type: string
      prefix:
        description: SI prefix (e.g., "G", "M", "K", "T")
        type: string
    type: object
host: localhost:8080
info:
  contact:
    email: support@clustercockpit.org
    name: ClusterCockpit Project
    url: https://github.com/ClusterCockpit
  description: API for batch job control.
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  title: ClusterCockpit REST API
  version: 1.0.0
paths:
  /api/clusters/:
    get:
      description: Get a list of all cluster configs. Specific cluster can be requested
        using query parameter.
      parameters:
      - description: Job Cluster
        in: query
        name: cluster
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Array of clusters
          schema:
            $ref: '#/definitions/api.GetClustersAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Lists all cluster configs
      tags:
      - Cluster query
  /api/jobs/:
    get:
      description: |-
        Get a list of all jobs. Filters can be applied using query parameters.
        Number of results can be limited by page. Results are sorted by descending startTime.
      parameters:
      - description: Job State
        enum:
        - running
        - completed
        - failed
        - cancelled
        - stopped
        - timeout
        in: query
        name: state
        type: string
      - description: Job Cluster
        in: query
        name: cluster
        type: string
      - description: 'Syntax: ''$from-$to'', as unix epoch timestamps in seconds'
        in: query
        name: start-time
        type: string
      - description: 'Items per page (Default: 25)'
        in: query
        name: items-per-page
        type: integer
      - description: 'Page Number (Default: 1)'
        in: query
        name: page
        type: integer
      - description: Include metadata (e.g. jobScript) in response
        in: query
        name: with-metadata
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Job array and page info
          schema:
            $ref: '#/definitions/api.GetJobsAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Lists all jobs
      tags:
      - Job query
  /api/jobs/{id}:
    get:
      description: |-
        Job to get is specified by database ID
        Returns full job resource information according to 'Job' scheme and all metrics according to 'JobData'.
      parameters:
      - description: Database ID of Job
        in: path
        name: id
        required: true
        type: integer
      - description: Include all available metrics
        in: query
        name: all-metrics
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Job resource
          schema:
            $ref: '#/definitions/api.GetJobAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: finding job failed: sql: no rows in
            result set'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get job meta and optional all metric data
      tags:
      - Job query
    post:
      consumes:
      - application/json
      description: |-
        Job to get is specified by database ID
        Returns full job resource information according to 'Job' scheme and all metrics according to 'JobData'.
      parameters:
      - description: Database ID of Job
        in: path
        name: id
        required: true
        type: integer
      - description: Array of metric names
        in: body
        name: request
        required: true
        schema:
          items:
            type: string
          type: array
      produces:
      - application/json
      responses:
        "200":
          description: Job resource
          schema:
            $ref: '#/definitions/api.GetJobAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: finding job failed: sql: no rows in
            result set'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get job meta and configurable metric data
      tags:
      - Job query
  /api/jobs/delete_job/:
    delete:
      consumes:
      - application/json
      description: Job to delete is specified by request body. All fields are required
        in this case.
      parameters:
      - description: All fields required
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.DeleteJobAPIRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/api.DefaultAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: finding job failed: sql: no rows in
            result set'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Remove a job from the sql database
      tags:
      - Job remove
  /api/jobs/delete_job/{id}:
    delete:
      description: Job to remove is specified by database ID. This will not remove
        the job from the job archive.
      parameters:
      - description: Database ID of Job
        in: path
        name: id
        required: true
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/api.DefaultAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: finding job failed: sql: no rows in
            result set'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Remove a job from the sql database
      tags:
      - Job remove
  /api/jobs/delete_job_before/{ts}:
    delete:
      description: Remove all jobs with start time before timestamp. The jobs will
        not be removed from the job archive.
      parameters:
      - description: Unix epoch timestamp
        in: path
        name: ts
        required: true
        type: integer
      - description: Omit jobs with tags from deletion
        in: query
        name: omit-tagged
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/api.DefaultAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: finding job failed: sql: no rows in
            result set'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Remove a job from the sql database
      tags:
      - Job remove
  /api/jobs/edit_meta/{id}:
    post:
      consumes:
      - application/json
      description: |-
        Edit key value pairs in job metadata json
        If a key already exists its content will be overwritten
      parameters:
      - description: Job Database ID
        in: path
        name: id
        required: true
        type: integer
      - description: Kay value pair to add
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.EditMetaRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Updated job resource
          schema:
            $ref: '#/definitions/schema.Job'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Job does not exist
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Edit meta-data json
      tags:
      - Job add and modify
  /api/jobs/start_job/:
    post:
      consumes:
      - application/json
      description: |-
        Job specified in request body will be saved to database as "running" with new DB ID.
        Job specifications follow the 'Job' scheme, API will fail to execute if requirements are not met.
      parameters:
      - description: Job to add
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/schema.Job'
      produces:
      - application/json
      responses:
        "201":
          description: Job added successfully
          schema:
            $ref: '#/definitions/api.DefaultAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: The combination of jobId, clusterId
            and startTime does already exist'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Adds a new job as "running"
      tags:
      - Job add and modify
  /api/jobs/stop_job/:
    post:
      description: |-
        Job to stop is specified by request body. All fields are required in this case.
        Returns full job resource information according to 'Job' scheme.
      parameters:
      - description: All fields required
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.StopJobAPIRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/schema.Job'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Resource not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: 'Unprocessable Entity: job has already been stopped'
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Marks job as completed and triggers archiving
      tags:
      - Job add and modify
  /api/jobs/tag_job/{id}:
    post:
      consumes:
      - application/json
      description: |-
        Adds tag(s) to a job specified by DB ID. Name and Type of Tag(s) can be chosen freely.
        Tag Scope for frontend visibility will default to "global" if none entered, other options: "admin" or specific username.
        If tagged job is already finished: Tag will be written directly to respective archive files.
      parameters:
      - description: Job Database ID
        in: path
        name: id
        required: true
        type: integer
      - description: Array of tag-objects to add
        in: body
        name: request
        required: true
        schema:
          items:
            $ref: '#/definitions/api.APITag'
          type: array
      produces:
      - application/json
      responses:
        "200":
          description: Updated job resource
          schema:
            $ref: '#/definitions/schema.Job'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Job or tag does not exist
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Adds one or more tags to a job
      tags:
      - Job add and modify
  /api/nodestats/:
    post:
      description: |-
        Returns a JSON-encoded list of users.
        Required query-parameter defines if all users or only users with additional special roles are returned.
      parameters:
      - description: Request body containing nodes and their states
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/api.UpdateNodeStatesRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/api.DefaultAPIResponse'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Deliver updated Slurm node states
      tags:
      - Nodestates
  /api/user/{id}:
    post:
      description: Allows admins to add/remove roles and projects for a user
      parameters:
      - description: Username
        in: path
        name: id
        required: true
        type: string
      - description: Role to add
        in: formData
        name: add-role
        type: string
      - description: Role to remove
        in: formData
        name: remove-role
        type: string
      - description: Project to add
        in: formData
        name: add-project
        type: string
      - description: Project to remove
        in: formData
        name: remove-project
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Success message
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update user roles and projects
      tags:
      - User
  /api/users/:
    delete:
      description: Deletes a user from the system
      parameters:
      - description: Username to delete
        in: formData
        name: username
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Success
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Delete a user
      tags:
      - User
    get:
      description: |-
        Returns a JSON-encoded list of users.
        Required query-parameter defines if all users or only users with additional special roles are returned.
      parameters:
      - description: If returned list should contain all users or only users with
          additional special roles
        in: query
        name: not-just-user
        required: true
        type: boolean
      produces:
      - application/json
      responses:
        "200":
          description: List of users returned successfully
          schema:
            items:
              $ref: '#/definitions/api.APIReturnedUser'
            type: array
        "400":
          description: Bad Request
          schema:
            type: string
        "401":
          description: Unauthorized
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Returns a list of users
      tags:
      - User
    post:
      description: Creates a new user with specified credentials and role
      parameters:
      - description: Username
        in: formData
        name: username
        required: true
        type: string
      - description: Password (not required for API users)
        in: formData
        name: password
        type: string
      - description: User role
        in: formData
        name: role
        required: true
        type: string
      - description: Full name
        in: formData
        name: name
        type: string
      - description: Email address
        in: formData
        name: email
        type: string
      - description: Project (required for managers)
        in: formData
        name: project
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Success message
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "422":
          description: Unprocessable Entity
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Create a new user
      tags:
      - User
  /configuration/:
    post:
      consumes:
      - multipart/form-data
      description: Updates a user's configuration key-value pair.
      parameters:
      - description: Configuration key
        in: formData
        name: key
        required: true
        type: string
      - description: Configuration value
        in: formData
        name: value
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: success
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update user configuration
      tags:
      - Frontend
  /debug/:
    post:
      description: This endpoint allows the users to print the content of
      parameters:
      - description: Selector
        in: query
        name: selector
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Debug dump
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Debug endpoint
      tags:
      - debug
  /free/:
    post:
      description: This endpoint allows the users to free the Buffers from the
      parameters:
      - description: up to timestamp
        in: query
        name: to
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: ok
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      tags:
      - free
  /healthcheck/:
    get:
      description: This endpoint allows the users to check if a node is healthy
      parameters:
      - description: Selector
        in: query
        name: selector
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Debug dump
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: HealthCheck endpoint
      tags:
      - healthcheck
  /jobs/tag_job/{id}:
    delete:
      consumes:
      - application/json
      description: |-
        Removes tag(s) from a job specified by DB ID. Name and Type of Tag(s) must match.
        Tag Scope is required for matching, options: "global", "admin". Private tags can not be deleted via API.
        If tagged job is already finished: Tag will be removed from respective archive files.
      parameters:
      - description: Job Database ID
        in: path
        name: id
        required: true
        type: integer
      - description: Array of tag-objects to remove
        in: body
        name: request
        required: true
        schema:
          items:
            $ref: '#/definitions/api.APITag'
          type: array
      produces:
      - application/json
      responses:
        "200":
          description: Updated job resource
          schema:
            $ref: '#/definitions/schema.Job'
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Job or tag does not exist
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Removes one or more tags from a job
      tags:
      - Job add and modify
  /jwt/:
    get:
      consumes:
      - multipart/form-data
      description: Generates a JWT token for a user. Admins can generate tokens for
        any user, regular users only for themselves.
      parameters:
      - description: Username to generate JWT for
        in: formData
        name: username
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: JWT token
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: User Not Found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Generate JWT token
      tags:
      - Frontend
  /machine_state/{cluster}/{host}:
    get:
      description: Retrieves stored machine state data for a specific cluster node.
        Validates cluster and host names to prevent path traversal.
      parameters:
      - description: Cluster name
        in: path
        name: cluster
        required: true
        type: string
      - description: Host name
        in: path
        name: host
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Machine state JSON data
          schema:
            type: object
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Machine state not enabled or file not found
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Retrieve machine state
      tags:
      - Machine State
    put:
      consumes:
      - application/json
      description: Stores machine state data for a specific cluster node. Validates
        cluster and host names to prevent path traversal.
      parameters:
      - description: Cluster name
        in: path
        name: cluster
        required: true
        type: string
      - description: Host name
        in: path
        name: host
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "201":
          description: Created
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Machine state not enabled
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Store machine state
      tags:
      - Machine State
  /notice/:
    post:
      consumes:
      - multipart/form-data
      description: Updates the notice.txt file content. Only admins are allowed. Content
        is limited to 10000 characters.
      parameters:
      - description: New notice content (max 10000 characters)
        in: formData
        name: new-content
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Update Notice Content Success
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Update system notice
      tags:
      - Config
  /roles/:
    get:
      description: Returns a list of valid user roles. Only admins are allowed.
      produces:
      - application/json
      responses:
        "200":
          description: List of role names
          schema:
            items:
              type: string
            type: array
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Get available roles
      tags:
      - Config
  /tags/:
    delete:
      consumes:
      - application/json
      description: |-
        Removes tags by type and name. Name and Type of Tag(s) must match.
        Tag Scope is required for matching, options: "global", "admin". Private tags can not be deleted via API.
        Tag wills be removed from respective archive files.
      parameters:
      - description: Array of tag-objects to remove
        in: body
        name: request
        required: true
        schema:
          items:
            $ref: '#/definitions/api.APITag'
          type: array
      produces:
      - text/plain
      responses:
        "200":
          description: Success Response
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "404":
          description: Job or tag does not exist
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
      summary: Removes all tags and job-relations for type:name tuple
      tags:
      - Tag remove
  /write/:
    post:
      consumes:
      - text/plain
      parameters:
      - description: If the lines in the body do not have a cluster tag, use this
          value instead.
        in: query
        name: cluster
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: ok
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/api.ErrorResponse'
        "500":
          description: Internal Server Error
          schema:
            $ref: '#/definitions/api.ErrorResponse'
      security:
      - ApiKeyAuth: []
securityDefinitions:
  ApiKeyAuth:
    in: header
    name: X-Auth-Token
    type: apiKey
swagger: "2.0"