cc-specifications/interfaces/rest/swagger.yaml

basePath: /api
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.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.DeleteJobApiResponse:
    properties:
      msg:
        type: string
    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.JobMeta'
        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.StartJobApiResponse:
    properties:
      msg:
        type: string
    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
  schema.Accelerator:
    properties:
      id:
        type: string
      model:
        type: string
      type:
        type: string
    type: object
  schema.Cluster:
    properties:
      metricConfig:
        items:
          $ref: '#/definitions/schema.MetricConfig'
        type: array
      name:
        type: string
      subClusters:
        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:
          type: number
        type: object
      exclusive:
        example: 1
        maximum: 2
        minimum: 0
        type: integer
      footprint:
        additionalProperties:
          type: number
        type: object
      id:
        type: integer
      jobId:
        example: 123000
        type: integer
      jobState:
        allOf:
        - $ref: '#/definitions/schema.JobState'
        enum:
        - completed
        - failed
        - cancelled
        - stopped
        - timeout
        - out_of_memory
        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
      resources:
        items:
          $ref: '#/definitions/schema.Resource'
        type: array
      smt:
        example: 4
        type: integer
      startTime:
        type: string
      subCluster:
        example: main
        type: string
      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:
        type: integer
      jobId:
        type: integer
    type: object
  schema.JobLinkResultList:
    properties:
      count:
        type: integer
      items:
        items:
          $ref: '#/definitions/schema.JobLink'
        type: array
    type: object
  schema.JobMeta:
    description: Meta data 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:
          type: number
        type: object
      exclusive:
        example: 1
        maximum: 2
        minimum: 0
        type: integer
      footprint:
        additionalProperties:
          type: number
        type: object
      id:
        type: integer
      jobId:
        example: 123000
        type: integer
      jobState:
        allOf:
        - $ref: '#/definitions/schema.JobState'
        enum:
        - completed
        - failed
        - cancelled
        - stopped
        - timeout
        - out_of_memory
        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
      resources:
        items:
          $ref: '#/definitions/schema.Resource'
        type: array
      smt:
        example: 4
        type: integer
      startTime:
        example: 1649723812
        minimum: 1
        type: integer
      statistics:
        additionalProperties:
          $ref: '#/definitions/schema.JobStatistics'
        type: object
      subCluster:
        example: main
        type: string
      tags:
        items:
          $ref: '#/definitions/schema.Tag'
        type: array
      user:
        example: abcd100h
        type: string
      walltime:
        example: 86400
        minimum: 1
        type: integer
    type: object
  schema.JobMetric:
    properties:
      series:
        items:
          $ref: '#/definitions/schema.Series'
        type: array
      statisticsSeries:
        $ref: '#/definitions/schema.StatsSeries'
      timestep:
        type: integer
      unit:
        $ref: '#/definitions/schema.Unit'
    type: object
  schema.JobState:
    enum:
    - running
    - completed
    - failed
    - cancelled
    - stopped
    - timeout
    - preempted
    - out_of_memory
    type: string
    x-enum-varnames:
    - JobStateRunning
    - JobStateCompleted
    - JobStateFailed
    - JobStateCancelled
    - JobStateStopped
    - JobStateTimeout
    - JobStatePreempted
    - JobStateOutOfMemory
  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:
        type: string
      alert:
        type: number
      caution:
        type: number
      energy:
        type: string
      footprint:
        type: string
      lowerIsBetter:
        type: boolean
      name:
        type: string
      normal:
        type: number
      peak:
        type: number
      scope:
        $ref: '#/definitions/schema.MetricScope'
      subClusters:
        items:
          $ref: '#/definitions/schema.SubClusterConfig'
        type: array
      timestep:
        type: integer
      unit:
        $ref: '#/definitions/schema.Unit'
    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:
        type: number
      max:
        type: number
      min:
        type: number
    type: object
  schema.MetricValue:
    properties:
      unit:
        $ref: '#/definitions/schema.Unit'
      value:
        type: number
    type: object
  schema.Resource:
    description: A resource used by a job
    properties:
      accelerators:
        items:
          type: string
        type: array
      configuration:
        type: string
      hostname:
        type: string
      hwthreads:
        items:
          type: integer
        type: array
    type: object
  schema.Series:
    properties:
      data:
        items:
          type: number
        type: array
      hostname:
        type: string
      id:
        type: string
      statistics:
        $ref: '#/definitions/schema.MetricStatistics'
    type: object
  schema.StatsSeries:
    properties:
      max:
        items:
          type: number
        type: array
      mean:
        items:
          type: number
        type: array
      median:
        items:
          type: number
        type: array
      min:
        items:
          type: number
        type: array
      percentiles:
        additionalProperties:
          items:
            type: number
          type: array
        type: object
    type: object
  schema.SubCluster:
    properties:
      coresPerSocket:
        type: integer
      energyFootprint:
        items:
          type: string
        type: array
      flopRateScalar:
        $ref: '#/definitions/schema.MetricValue'
      flopRateSimd:
        $ref: '#/definitions/schema.MetricValue'
      footprint:
        items:
          type: string
        type: array
      memoryBandwidth:
        $ref: '#/definitions/schema.MetricValue'
      metricConfig:
        items:
          $ref: '#/definitions/schema.MetricConfig'
        type: array
      name:
        type: string
      nodes:
        type: string
      processorType:
        type: string
      socketsPerNode:
        type: integer
      threadsPerCore:
        type: integer
      topology:
        $ref: '#/definitions/schema.Topology'
    type: object
  schema.SubClusterConfig:
    properties:
      alert:
        type: number
      caution:
        type: number
      energy:
        type: string
      footprint:
        type: string
      lowerIsBetter:
        type: boolean
      name:
        type: string
      normal:
        type: number
      peak:
        type: number
      remove:
        type: boolean
    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:
        items:
          $ref: '#/definitions/schema.Accelerator'
        type: array
      core:
        items:
          items:
            type: integer
          type: array
        type: array
      die:
        items:
          items:
            type: integer
          type: array
        type: array
      memoryDomain:
        items:
          items:
            type: integer
          type: array
        type: array
      node:
        items:
          type: integer
        type: array
      socket:
        items:
          items:
            type: integer
          type: array
        type: array
    type: object
  schema.Unit:
    properties:
      base:
        type: string
      prefix:
        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:
  /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
  /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
  /jobs/{id}:
    get:
      description: |-
        Job to get is specified by database ID
        Returns full job resource information according to 'JobMeta' 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 'JobMeta' 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
  /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.DeleteJobApiResponse'
        "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
  /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.DeleteJobApiResponse'
        "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
  /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
      produces:
      - application/json
      responses:
        "200":
          description: Success message
          schema:
            $ref: '#/definitions/api.DeleteJobApiResponse'
        "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
  /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
  /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 'JobMeta' 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.JobMeta'
      produces:
      - application/json
      responses:
        "201":
          description: Job added successfully
          schema:
            $ref: '#/definitions/api.StartJobApiResponse'
        "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
  /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 'JobMeta' 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.JobMeta'
        "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: Marks job as completed and triggers archiving
      tags:
      - Job add and modify
  /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
  /user/{id}:
    post:
      consumes:
      - multipart/form-data
      description: |-
        Modifies user defined by username (id) in one of four possible ways.
        If more than one formValue is set then only the highest priority field is used.
        Only accessible from IPs registered with apiAllowedIPs configuration option.        
      parameters:
      - description: Database ID of User
        in: path
        name: id
        required: true
        type: string
      - description: 'Priority 1: Role to add'
        enum:
        - admin
        - support
        - manager
        - user
        - api
        in: formData
        name: add-role
        type: string
      - description: 'Priority 2: Role to remove'
        enum:
        - admin
        - support
        - manager
        - user
        - api
        in: formData
        name: remove-role
        type: string
      - description: 'Priority 3: Project to add'
        in: formData
        name: add-project
        type: string
      - description: 'Priority 4: Project to remove'
        in: formData
        name: remove-project
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Success Response Message
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            type: string
        "401":
          description: Unauthorized
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            type: string
        "422":
          description: 'Unprocessable Entity: The user could not be updated'
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Updates an existing user
      tags:
      - User
  /users/:
    delete:
      consumes:
      - multipart/form-data
      description: |-
        User defined by username in form data will be deleted from database.
        Only accessible from IPs registered with apiAllowedIPs configuration option.        
      parameters:
      - description: User ID to delete
        in: formData
        name: username
        required: true
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: User deleted successfully
        "400":
          description: Bad Request
          schema:
            type: string
        "401":
          description: Unauthorized
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            type: string
        "422":
          description: 'Unprocessable Entity: deleting user failed'
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Deletes 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.
        Only accessible from IPs registered with apiAllowedIPs configuration option.        
      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:
      consumes:
      - multipart/form-data
      description: |-
        User specified in form data will be saved to database.
        Only accessible from IPs registered with apiAllowedIPs configuration option.        
      parameters:
      - description: Unique user ID
        in: formData
        name: username
        required: true
        type: string
      - description: User password
        in: formData
        name: password
        required: true
        type: string
      - description: User role
        enum:
        - admin
        - support
        - manager
        - user
        - api
        in: formData
        name: role
        required: true
        type: string
      - description: Managed project, required for new manager role user
        in: formData
        name: project
        type: string
      - description: Users name
        in: formData
        name: name
        type: string
      - description: Users email
        in: formData
        name: email
        type: string
      produces:
      - text/plain
      responses:
        "200":
          description: Success Response
          schema:
            type: string
        "400":
          description: Bad Request
          schema:
            type: string
        "401":
          description: Unauthorized
          schema:
            type: string
        "403":
          description: Forbidden
          schema:
            type: string
        "422":
          description: 'Unprocessable Entity: creating user failed'
          schema:
            type: string
        "500":
          description: Internal Server Error
          schema:
            type: string
      security:
      - ApiKeyAuth: []
      summary: Adds a new user
      tags:
      - User
securityDefinitions:
  ApiKeyAuth:
    in: header
    name: X-Auth-Token
    type: apiKey
swagger: "2.0"