Job operations¶

Changed in version 1.12.0: API versioning

Use these operations to query the currently selected file and start/cancel/restart/pause the actual print job.

Issue a job command¶

POST /api/job¶

Job commands allow starting, pausing and cancelling print jobs. Available commands are:

start

Starts the print of the currently selected file. For selecting a file, see Issue a file command. If a print job is already active, a 409 Conflict will be returned.

cancel

Cancels the current print job. If no print job is active (either paused or printing), a 409 Conflict will be returned.

restart

Restart the print of the currently selected file from the beginning. There must be an active print job for this to work and the print job must currently be paused. If either is not the case, a 409 Conflict will be returned.

Equivalent to issuing a cancel command while paused, directly followed by a start command.

pause

Pauses/resumes/toggles the current print job. Accepts one optional additional parameter action specifying which action to take. Valid values for this parameter are:

pause: Pauses the current job if it’s printing, does nothing if it’s already paused.
resume: Resumes the current job if it’s paused, does nothing if it’s printing.
toggle: Toggles the pause state of the job, pausing it if it’s printing and resuming it if it’s currently paused.

In order to stay backwards compatible to earlier iterations of this API, the default action to take if no action parameter is supplied is to toggle the print job status.

If no print job is active (either paused or printing), a 409 Conflict will be returned.

Note

While the approach to implement pause/resume/toggle behaviour through sub commands via the action parameter instead of having dedicated pause, resume and toggle commands seems clumsy, this path was chosen to have the API stay backwards compatible to prior versions which only offered the toggle behaviour under the pause command.

Upon success, a status code of 204 No Content and an empty body is returned.

Requires the PRINT permission.

Example Start Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "start"
}

HTTP/1.1 204 No Content

Example Cancel Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "cancel"
}

HTTP/1.1 204 No Content

Example Restart Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "restart"
}

HTTP/1.1 204 No Content

Example Pause Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "pause",
  "action": "pause"
}

HTTP/1.1 204 No Content

Example Resume Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "pause",
  "action": "resume"
}

HTTP/1.1 204 No Content

Example Pause Toggle Request

POST /api/job HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer abcdef...

{
  "command": "pause",
  "action": "toggle"
}

HTTP/1.1 204 No Content

JSON Parameters:¶

command (string) – The command to issue, either start, restart, pause or cancel

Status Codes:¶

204 No Content – No error
409 Conflict – If the printer is not operational or the current print job state does not match the preconditions for the command.

Retrieve information about the current job¶

API version 1.12.0+ API version pre 1.12.0

GET /api/job¶

Retrieve information about the current job (if there is one).

Returns a 200 OK with a Job information response (pre 1.12.0) in the body.

Requires the STATUS permission.

Example

GET /api/job HTTP/1.1
Host: example.com
Authorization: Bearer abcdef...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "job": {
    "file": {
      "name": "whistle_v2.gcode",
      "origin": "local",
      "size": 1468987,
      "date": 1378847754
    },
    "estimatedPrintTime": 8811,
    "filament": {
      "tool0": {
        "length": 810,
        "volume": 5.36
      }
    },
    "user": "someone"
  },
  "progress": {
    "completion": 0.2298468264184775,
    "filepos": 337942,
    "printTime": 276,
    "printTimeLeft": 912,
    "printTimeLeftOrigin": "linear"
  },
  "state": "Printing"
}

Status Codes:¶

200 OK – No error

GET /api/job¶

Retrieve information about the current job (if there is one).

Returns a 200 OK with a Job information response (pre 1.12.0) in the body.

Requires the STATUS permission.

Example

GET /api/job HTTP/1.1
Host: example.com
Authorization: Bearer abcdef...

HTTP/1.1 200 OK
Content-Type: application/json

{
  "job": {
    "file": {
      "name": "whistle_v2.gcode",
      "origin": "local",
      "size": 1468987,
      "date": 1378847754
    },
    "estimatedPrintTime": 8811,
    "lastPrintTime": null,
    "filament": {
      "tool0": {
        "length": 810,
        "volume": 5.36
      }
    },
    "user": "someone"
  },
  "progress": {
    "completion": 0.2298468264184775,
    "filepos": 337942,
    "printTime": 276,
    "printTimeLeft": 912,
    "printTimeLeftOrigin": "linear"
  },
  "state": "Printing"
}

Status Codes:¶

200 OK – No error

Data model¶

Job information response¶

Name	Type	Description	Default
`job.*`		Information about the current job
`job.file.*`		File being printed
`job.file.name`	`str`	Internal name of the file being printed	unset
`job.file.path`	`str`	Path of the file being printed	unset
`job.file.display`	`str`	Display name of the file being printed	unset
`job.file.origin`	`str`	Storage of the file being printed	unset
`job.file.size`	`int`	Size of the file being printed in bytes	unset
`job.file.date`	`int`	Last modification date of the file being printed as timestamp	unset
`job.estimatedPrintTime`	`float`	Estimated print time in seconds, if known	unset
`job.filament`	`dict[str, Optional[dict[str, float]]]`	Filament usage information as mapping from printer profile to mappings from tool to used length, if known	unset
`job.user`	`str`	The user who started the job, if known	unset
`progress.*`		Information about the current job’s progress
`progress.completion`	`int`	Completion in percentage, if known	unset
`progress.filepos`	`int`	Current file position, if known	unset
`progress.printTime`	`int`	Print time so far	unset
`progress.printTimeLeft`	`int`	Estimated print time left	unset
`progress.printTimeLeftOrigin`	`str`	Origin of estimate. E.g.: `linear`: based on a linear approximation of the progress in file in bytes vs time `analysis`: based on an analysis of the file `estimate`: calculated estimate after stabilization of linear estimation `average`: based on the average total from past prints of the same model against the same printer profile `mixed-analysis`: mixture of `estimate` and `analysis` `mixed-average`: mixture of `estimate` and `average` `printer`: estimate by printer	unset
`state`	`str`	Current state	required
`error`	`str`	Error, if any	unset

Job information response (pre 1.12.0)¶

Name	Type	Description	Default
`job.*`		Information about the current job
`job.file.*`		File being printed
`job.file.name`	`str`	Internal name of the file being printed	unset
`job.file.path`	`str`	Path of the file being printed	unset
`job.file.display`	`str`	Display name of the file being printed	unset
`job.file.origin`	`str`	Storage of the file being printed	unset
`job.file.size`	`int`	Size of the file being printed in bytes	unset
`job.file.date`	`int`	Last modification date of the file being printed as timestamp	unset
`job.estimatedPrintTime`	`float`	Estimated print time in seconds, if known	unset
`job.filament`	`dict[str, Optional[dict[str, float]]]`	Filament usage information as mapping from printer profile to mappings from tool to used length, if known	unset
`job.user`	`str`	The user who started the job, if known	unset
`job.lastPrintTime`	`float`	The last print time in seconds	unset
`progress.*`		Information about the current job’s progress
`progress.completion`	`int`	Completion in percentage, if known	unset
`progress.filepos`	`int`	Current file position, if known	unset
`progress.printTime`	`int`	Print time so far	unset
`progress.printTimeLeft`	`int`	Estimated print time left	unset
`progress.printTimeLeftOrigin`	`str`	Origin of estimate. E.g.: `linear`: based on a linear approximation of the progress in file in bytes vs time `analysis`: based on an analysis of the file `estimate`: calculated estimate after stabilization of linear estimation `average`: based on the average total from past prints of the same model against the same printer profile `mixed-analysis`: mixture of `estimate` and `analysis` `mixed-average`: mixture of `estimate` and `average` `printer`: estimate by printer	unset
`state`	`str`	Current state	required
`error`	`str`	Error, if any	unset