Job operations¶
Use these operations to query the currently selected file and start/cancel/restart/pause the actual print job.
Contents
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 astart
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 dedicatedpause
,resume
andtoggle
commands seems clumsy, this path was chosen to have the API stay backwards compatible to prior versions which only offered the toggle behaviour under thepause
command.
Upon success, a status code of 204 No Content and an empty body is returned.
Requires user rights.
Example Start Request
POST /api/job HTTP/1.1 Host: example.com Content-Type: application/json X-Api-Key: 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 X-Api-Key: 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 X-Api-Key: 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 X-Api-Key: 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 X-Api-Key: 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 X-Api-Key: abcdef... { "command": "pause", "action": "toggle" }
HTTP/1.1 204 No Content
JSON Parameters: - command (string) – The command to issue, either
start
,restart
,pause
orcancel
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¶
-
GET
/api/job
¶ Retrieve information about the current job (if there is one).
Returns a 200 OK with a Job information response in the body.
Example
GET /api/job HTTP/1.1 Host: example.com X-Api-Key: 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": { "length": 810, "volume": 5.36 } }, "progress": { "completion": 0.2298468264184775, "filepos": 337942, "printTime": 276, "printTimeLeft": 912 }, "state": "Printing" }
Status Codes: - 200 OK – No error
Data model¶
Job information response¶
Name | Multiplicity | Type | Description |
---|---|---|---|
job |
1 | Job information | Information regarding the target of the current print job |
progress |
1 | Progress information | Information regarding the progress of the current print job |
state |
1 | String | A textual representation of the current state of the job, i.e. “Operational”, “Printing”, “Pausing”, “Paused”, “Cancelling”, “Error” or “Offline”. |