Job operations

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

Contents

• Job operations

  • Issue a job command

  • Retrieve information about the current job

  • Data model

    • Job information response

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
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 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

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.

Requires the STATUS permission.

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": {
      "tool0": {
        "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 or connection, e.g. “Operational”, “Printing”, “Pausing”, “Paused”, “Cancelling”, “Error”, “Offline”, “Offline after error”, “Opening serial connection”, … – please note that this list is not exhaustive!
error	0..1	String	Any error message for the job or connection, only set if there has been an error.