basePath: /api definitions: api.ApiTag: properties: name: description: Tag Name example: Testjob 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.ErrorResponse: properties: error: description: Error Message type: string status: description: Statustext of Errorcode type: string 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.StartJobApiResponse: properties: id: description: Database ID of new job type: integer type: object api.StopJobApiRequest: properties: cluster: description: Cluster of job example: fritz type: string jobId: description: Cluster Job ID of job example: 123000 type: integer jobState: allOf: - $ref: '#/definitions/schema.JobState' description: Final job state enum: - completed - failed - cancelled - stopped - timeout example: completed startTime: description: Start Time of job as epoch example: 1649723812 type: integer stopTime: description: Stop Time of job as epoch example: 1649763839 type: integer required: - jobState - stopTime type: object schema.Job: description: Information of a HPC job. properties: arrayJobId: description: The unique identifier of an array job example: 123000 type: integer cluster: description: The unique identifier of a cluster example: fritz type: string duration: description: Duration of job in seconds (Min > 0) example: 43200 minimum: 1 type: integer exclusive: description: 'Specifies how nodes are shared: 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive (Default), 2 - Shared among multiple jobs of same user' example: 1 maximum: 2 minimum: 0 type: integer id: description: The unique identifier of a job in the database type: integer jobId: description: The unique identifier of a job example: 123000 type: integer jobState: allOf: - $ref: '#/definitions/schema.JobState' description: Final state of job enum: - completed - failed - cancelled - stopped - timeout - out_of_memory example: completed metaData: additionalProperties: type: string description: Additional information about the job type: object monitoringStatus: description: 'State of monitoring system during job run: 0 - Disabled, 1 - Running or Archiving (Default), 2 - Archiving Failed, 3 - Archiving Successfull' example: 1 maximum: 3 minimum: 0 type: integer numAcc: description: Number of accelerators used (Min > 0) example: 2 minimum: 1 type: integer numHwthreads: description: Number of HWThreads used (Min > 0) example: 20 minimum: 1 type: integer numNodes: description: Number of nodes used (Min > 0) example: 2 minimum: 1 type: integer partition: description: The Slurm partition to which the job was submitted example: main type: string project: description: The unique identifier of a project example: abcd200 type: string resources: description: Resources used by job items: $ref: '#/definitions/schema.Resource' type: array smt: description: SMT threads used by job example: 4 type: integer startTime: description: Start time as 'time.Time' data type type: string subCluster: description: The unique identifier of a sub cluster example: main type: string tags: description: List of tags items: $ref: '#/definitions/schema.Tag' type: array user: description: The unique identifier of a user example: abcd100h type: string walltime: description: Requested walltime of job in seconds (Min > 0) example: 86400 minimum: 1 type: integer type: object schema.JobMeta: description: Meta data information of a HPC job. properties: arrayJobId: description: The unique identifier of an array job example: 123000 type: integer cluster: description: The unique identifier of a cluster example: fritz type: string duration: description: Duration of job in seconds (Min > 0) example: 43200 minimum: 1 type: integer exclusive: description: 'Specifies how nodes are shared: 0 - Shared among multiple jobs of multiple users, 1 - Job exclusive (Default), 2 - Shared among multiple jobs of same user' example: 1 maximum: 2 minimum: 0 type: integer id: description: The unique identifier of a job in the database type: integer jobId: description: The unique identifier of a job example: 123000 type: integer jobState: allOf: - $ref: '#/definitions/schema.JobState' description: Final state of job enum: - completed - failed - cancelled - stopped - timeout - out_of_memory example: completed metaData: additionalProperties: type: string description: Additional information about the job type: object monitoringStatus: description: 'State of monitoring system during job run: 0 - Disabled, 1 - Running or Archiving (Default), 2 - Archiving Failed, 3 - Archiving Successfull' example: 1 maximum: 3 minimum: 0 type: integer numAcc: description: Number of accelerators used (Min > 0) example: 2 minimum: 1 type: integer numHwthreads: description: Number of HWThreads used (Min > 0) example: 20 minimum: 1 type: integer numNodes: description: Number of nodes used (Min > 0) example: 2 minimum: 1 type: integer partition: description: The Slurm partition to which the job was submitted example: main type: string project: description: The unique identifier of a project example: abcd200 type: string resources: description: Resources used by job items: $ref: '#/definitions/schema.Resource' type: array smt: description: SMT threads used by job example: 4 type: integer startTime: description: Start epoch time stamp in seconds (Min > 0) example: 1649723812 minimum: 1 type: integer statistics: additionalProperties: $ref: '#/definitions/schema.JobStatistics' description: Metric statistics of job type: object subCluster: description: The unique identifier of a sub cluster example: main type: string tags: description: List of tags items: $ref: '#/definitions/schema.Tag' type: array user: description: The unique identifier of a user example: abcd100h type: string walltime: description: Requested walltime of job in seconds (Min > 0) example: 86400 minimum: 1 type: integer 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: description: Metric unit (see schema/unit.schema.json) example: GHz type: string type: object schema.Resource: description: A resource used by a job properties: accelerators: description: List of of accelerator device ids items: type: string type: array configuration: description: The configuration options of the node type: string hostname: description: Name of the host (= node) type: string hwthreads: description: List of OS processor ids items: type: integer type: array type: object schema.Tag: description: Defines a tag using name and type. properties: id: description: The unique DB identifier of a tag type: integer name: description: Tag Name example: Testjob type: string type: description: Tag Type example: Debug 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: 0.2.0 paths: /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' "500": description: Internal Server Error schema: $ref: '#/definitions/api.ErrorResponse' security: - ApiKeyAuth: [] summary: Lists all jobs tags: - 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: - 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: - 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: - remove /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: - 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: - add and modify /jobs/stop_job/{id}: post: consumes: - application/json description: |- Job to stop is specified by database ID. Only stopTime and final state are required in request body. Returns full job resource information according to 'JobMeta' scheme. parameters: - description: Database ID of Job in: path name: id required: true type: integer - description: stopTime and final state in request body in: body name: request required: true schema: $ref: '#/definitions/api.StopJobApiRequest' produces: - application/json responses: "200": description: Job resource 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: - 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. 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: - add and modify securityDefinitions: ApiKeyAuth: in: header name: X-Auth-Token type: apiKey swagger: "2.0" tags: - name: Job API