Printer operations 

Contents

Printer control is mostly achieved through the use of commands, issued to resources reflecting components of the printer. OctoPrint currently knows the following components:

Print head: Print head commands allow jogging and homing the print head in all three axes. Querying the resource is currently not supported. See Issue a print head command.
Tool: Tool commands allow setting the temperature and temperature offsets for the printer’s hotends/tools. Querying the corresponding resource returns temperature information including an optional history. See Issue a tool command.
Bed: Bed commands allow setting the temperature and temperature offset for the printer’s heated bed. Querying the corresponding resource returns temperature information including an optional history. Note that Bed commands are only available if the currently selected printer profile has a heated bed. See Issue a bed command.
Chamber: Chamber commands allow setting the temperature and temperature offset for the printer’s heated chamber. Querying the corresponding resource returns temperature information including an option history. Note that Chamber commands are only available if the currently selected printer profile has a heated chamber. See Issue a chamber command.
SD card: SD commands allow initialization, refresh and release of the printer’s SD card (if available). Querying the corresponding resource returns the current SD card state. See Issue an SD command.

Besides that, OctoPrint also provides a full state report of the printer.

Note

You might be wondering why all command responses below only return a 204 with an empty body instead of the output of the just sent commands. There are two reasons for this.

OctoPrint’s internal webserver is single threaded and can only handle one request at a time. This is not a problem generally since asynchronous programming allows to just have one request which is waiting for data from a long running backend operation to sleep while handling other requests. The internal framework used for providing the REST API though, Flask, is based on WSGI, which is synchronous in nature. This means that it is impossible to wait in a non blocking wait while handling a request on the REST API. So in order to return the response of a command sent to the printer, the single thread of the webserver would have to be blocked by the API while the response wasn’t available yet. Which in turn would mean that the whole web server would stop responding while waiting for the printer to reply, which, depending on the command in question (e.g. homing) can take a long while. That would be a bad idea.

The second reason is that thanks to a large number of firmwares out there having a particular bug that makes it impossible to track the output of sent commands, identifying the correct response to a given sent command is pretty much hit-and-miss. That situation gets even worse considering that it’s next to impossible to distinguish firmware versions which have that bug from firmware versions which don’t have it.

Hence OctoPrint currently doesn’t offer any synchronous way of retrieving the output of responses from the printer. If you need the printer’s serial communication, you’ll need to subscribe to push updates.

Retrieve the current printer state 

GET /api/printer

Retrieves the current state of the printer. Returned information includes:

temperature information (see also Retrieve the current tool state and Retrieve the current bed state)
sd state (if available, see also Retrieve the current SD state)
general printer state

Temperature information can also be made to include the printer’s temperature history by supplying the history query parameter. The amount of data points to return here can be limited using the limit query parameter.

Clients can specific a list of attributes to not return in the response (e.g. if they don’t need it) via the exclude query parameter.

Returns a 200 OK with a Full State Response in the body upon success.

Requires the STATUS permission.

Example 1

Include temperature history data, but limit it to two entries.

GET /api/printer?history=true&limit=2 HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "temperature": {
    "tool0": {
      "actual": 214.8821,
      "target": 220.0,
      "offset": 0
    },
    "tool1": {
      "actual": 25.3,
      "target": null,
      "offset": 0
    },
    "bed": {
      "actual": 50.221,
      "target": 70.0,
      "offset": 5
    },
    "history": [
      {
        "time": 1395651928,
        "tool0": {
          "actual": 214.8821,
          "target": 220.0
        },
        "tool1": {
          "actual": 25.3,
          "target": null
        },
        "bed": {
          "actual": 50.221,
          "target": 70.0
        }
      },
      {
        "time": 1395651926,
        "tool0": {
          "actual": 212.32,
          "target": 220.0
        },
        "tool1": {
          "actual": 25.1,
          "target": null
        },
        "bed": {
          "actual": 49.1123,
          "target": 70.0
        }
      }
    ]
  },
  "sd": {
    "ready": true
  },
  "state": {
    "text": "Operational",
    "flags": {
      "operational": true,
      "paused": false,
      "printing": false,
      "cancelling": false,
      "pausing": false,
      "sdReady": true,
      "error": false,
      "ready": true,
      "closedOrError": false
    }
  }
}

Example 2

Exclude temperature and sd data.

GET /api/printer?exclude=temperature,sd HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "state": {
    "text": "Operational",
    "flags": {
      "operational": true,
      "paused": false,
      "printing": false,
      "cancelling": false,
      "pausing": false,
      "sdReady": true,
      "error": false,
      "ready": true,
      "closedOrError": false
    }
  }
}

Query Parameters

exclude – An optional comma-separated list of fields to exclude from the response (e.g. if not needed by the client). Valid values to supply here are temperature, sd and state.
history – If set to true (or: yes, y, 1), history information will be included in the response too. If no limit parameter is given, all available temperature history data will be returned.
limit – If set to an integer (n), only the last n data points from the printer’s temperature history will be returned. Will be ignored if history is not enabled.

Status Codes

200 OK – No error
409 Conflict – If the printer is not operational.

Issue a print head command 

POST /api/printer/printhead

Print head commands allow jogging and homing the print head in all three axes. Available commands are:

jog

Jogs the print head (relatively) by a defined amount in one or more axes. Additional parameters are:

x: Optional. Amount/coordinate to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm.
y: Optional. Amount/coordinate to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm.
z: Optional. Amount/coordinate to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm.
absolute: Optional. Boolean value specifying whether to move relative to current position (provided axes values are relative amounts) or to absolute position (provided axes values are coordinates)
speed: Optional. Speed at which to move. If not provided, minimum speed for all selected axes from printer profile will be used. If provided but false, no speed parameter will be appended to the command. Otherwise interpreted as an integer signifying the speed in mm/min, to append to the command.

home

Homes the print head in all of the given axes. Additional parameters are:

axes: A list of axes which to home, valid values are one or more of x, y, z.

feedrate

Changes the feedrate factor to apply to the movements of the axes.

factor: The new factor, percentage between 50 and 200% as integer (50 to 200) or float (0.5 to 2.0).

All of these commands except feedrate may only be sent if the printer is currently operational and not printing. Otherwise a 409 Conflict is returned.

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

Requires the CONTROL permission.

Example Jog Request

Jog the print head by 10mm in X, -5mm in Y and 0.02mm in Z.

POST /api/printer/printhead HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "jog",
  "x": 10,
  "y": -5,
  "z": 0.02
}

HTTP/1.1 204 No Content

Example Home Request

Home the X and Y axes.

POST /api/printer/printhead HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "home",
  "axes": ["x", "y"]
}

HTTP/1.1 204 No Content

Example feed rate request (1/2)

Set the feed rate factor to 105% using an integer argument.

POST /api/printer/printhead HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "feedrate",
  "factor": 105
}

HTTP/1.1 204 No Content

Example feed rate request (2/2)

Set the feed rate factor to 105% using a float argument.

POST /api/printer/printhead HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "feedrate",
  "factor": 1.05
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – The command to issue, either jog or home.
x (number) – jog command: The amount to travel on the X axis in mm.
y (number) – jog command: The amount to travel on the Y axis in mm.
z (number) – jog command: The amount to travel on the Z axis in mm.
axes (array) – home command: The axes which to home, valid values are one or more of x, y and z.
factor (number) – feedrate command: The factor to apply to the feed rate, percentage between 50 and 200% as integer or float.

Status Codes

204 No Content – No error
400 Bad Request – Invalid axis specified, invalid value for travel amount for a jog command or factor for feed rate or otherwise invalid request.
409 Conflict – If the printer is not operational or currently printing.

Issue a tool command 

POST /api/printer/tool

Tool commands allow setting the temperature and temperature offsets for the printer’s tools (hotends), selecting the current tool and extruding/retracting from the currently selected tool. Available commands are:

target

Sets the given target temperature on the printer’s tools. Additional parameters:

targets: Target temperature(s) to set, properties must match the format tool{n} with n being the tool’s index starting with 0. A value of 0 will turn the heater off.

offset

Sets the given temperature offset on the printer’s tools. Additional parameters:

offsets: Offset(s) to set, properties must match the format tool{n} with n being the tool’s index starting with 0.

select

Selects the printer’s current tool. Additional parameters:

tool: Tool to select, format tool{n} with n being the tool’s index starting with 0.

extrude

Extrudes the given amount of filament from the currently selected tool. Additional parameters:

amount: The amount of filament to extrude in mm. May be negative to retract.
speed: Optional. Speed at which to extrude. If not provided, maximum speed for E axis from printer profile will be used. Otherwise interpreted as an integer signifying the speed in mm/min, to append to the command.

flowrate

Changes the flow rate factor to apply to extrusion of the tool.

factor: The new factor, percentage between 75 and 125% as integer (75 to 125) or float (0.75 to 1.25).

All of these commands may only be sent if the printer is currently operational and – in case of select and extrude – not printing. Otherwise a 409 Conflict is returned.

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

Requires the CONTROL permission.

Example Target Temperature Request

Set the target temperature for the printer’s first hotend to 220°C and the printer’s second extruder to 205°C.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "target",
  "targets": {
    "tool0": 220,
    "tool1": 205
  }
}

HTTP/1.1 204 No Content

Example Offset Temperature Request

Set the offset for temperatures on tool0 to +10°C and on tool1 to -5°C.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "offset",
  "offsets": {
    "tool0": 10,
    "tool1": -5
  }
}

HTTP/1.1 204 No Content

Example Tool Select Request

Select the second hotend of the printer for any following extrude commands.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "select",
  "tool": "tool1"
}

HTTP/1.1 204 No Content

Example Extrude Request

Extrude 5mm on the currently selected tool.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "extrude",
  "amount": 5
}

HTTP/1.1 204 No Content

Example Retract Request

Retract 3mm of filament on the currently selected tool.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "extrude",
  "amount": -3
}

HTTP/1.1 204 No Content

Example flow rate request (1/2)

Set the flow rate factor to 95% using an integer attribute.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "flowrate",
  "factor": 95
}

HTTP/1.1 204 No Content

Example flow rate request (2/2)

Set the flow rate factor to 95% using a float attribute.

POST /api/printer/tool HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "flowrate",
  "factor": 0.95
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – The command to issue, either target, offset, select or extrude.
targets (object) – target command: The target temperatures to set. Valid properties have to match the format tool{n}.
offsets (object) – offset command: The offset temperature to set. Valid properties have to match the format tool{n}.
tool (object) – select command: The tool to select, value has to match the format tool{n}.
amount (object) – extrude command: The amount of filament to extrude from the currently selected tool.
factor (number) – flowrate command: The factor to apply to the flow rate, percentage between 75 and 125% as integer or float.

Status Codes

204 No Content – No error
400 Bad Request – If targets or offsets contains a property or tool contains a value not matching the format tool{n}, the target/offset temperature, extrusion amount or flow rate factor is not a valid number or outside of the supported range, or if the request is otherwise invalid.
409 Conflict – If the printer is not operational or – in case of select or extrude – currently printing.

Retrieve the current tool state 

GET /api/printer/tool

Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for all of the printer’s available tools.

It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.

Returns a 200 OK with a Temperature Response in the body upon success.

Requires the STATUS permission.

Note

If you want both tool and bed temperature information at the same time, take a look at Retrieve the current printer state.

Example

Query the tool temperature data and also include the temperature history but limit it to two entries.

GET /api/printer/tool?history=true&limit=2 HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "tool0": {
    "actual": 214.8821,
    "target": 220.0,
    "offset": 0
  },
  "tool1": {
    "actual": 25.3,
    "target": null,
    "offset": 0
  },
  "history": [
    {
      "time": 1395651928,
      "tool0": {
        "actual": 214.8821,
        "target": 220.0
      },
      "tool1": {
        "actual": 25.3,
        "target": null
      }
    },
    {
      "time": 1395651926,
      "tool0": {
        "actual": 212.32,
        "target": 220.0
      },
      "tool1": {
        "actual": 25.1
      }
    }
  ]
}

Query Parameters

history – If set to true (or: yes, y, 1), history information will be included in the response too. If no limit parameter is given, all available temperature history data will be returned.
limit – If set to an integer (n), only the last n data points from the printer’s temperature history will be returned. Will be ignored if history is not enabled.

Status Codes

200 OK – No error
409 Conflict – If the printer is not operational.

Issue a bed command 

POST /api/printer/bed

Bed commands allow setting the temperature and temperature offsets for the printer’s heated bed. Available commands are:

target

Sets the given target temperature on the printer’s bed. Additional parameters:

target: Target temperature to set. A value of 0 will turn the heater off.

offset

Sets the given temperature offset on the printer’s bed. Additional parameters:

offset: Offset to set.

All of these commands may only be sent if the printer is currently operational. Otherwise a 409 Conflict is returned.

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

If no heated bed is configured for the currently selected printer profile, the resource will return an 409 Conflict.

Requires the CONTROL permission.

Example Target Temperature Request

Set the target temperature for the printer’s heated bed to 75°C.

POST /api/printer/bed HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "target",
  "target": 75
}

HTTP/1.1 204 No Content

Example Offset Temperature Request

Set the temperature offset for the heated bed to -5°C.

POST /api/printer/bed HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "offset",
  "offset": -5
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – The command to issue, either target or offset.
target (object) – target command: The target temperature to set.
offset (object) – offset command: The offset temperature to set.

Status Codes

204 No Content – No error
400 Bad Request – If target or offset is not a valid number or outside of the supported range, or if the request is otherwise invalid.
409 Conflict – If the printer is not operational or the selected printer profile does not have a heated bed.

Retrieve the current bed state 

GET /api/printer/bed

Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated bed.

It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.

Returns a 200 OK with a Temperature Response in the body upon success.

If no heated bed is configured for the currently selected printer profile, the resource will return an 409 Conflict.

Requires the STATUS permission.

Note

If you want tool, bed and chamber temperature information at the same time, take a look at Retrieve the current printer state.

Example

Query the bed temperature data and also include the temperature history but limit it to two entries.

GET /api/printer/bed?history=true&limit=2 HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "bed": {
    "actual": 50.221,
    "target": 70.0,
    "offset": 5
  },
  "history": [
    {
      "time": 1395651928,
      "bed": {
        "actual": 50.221,
        "target": 70.0
      }
    },
    {
      "time": 1395651926,
      "bed": {
        "actual": 49.1123,
        "target": 70.0
      }
    }
  ]
}

Query Parameters

history – If set to true (or: yes, y, 1), history information will be included in the response too. If no limit parameter is given, all available temperature history data will be returned.
limit – If set to an integer (n), only the last n data points from the printer’s temperature history will be returned. Will be ignored if history is not enabled.

Status Codes

200 OK – No error
409 Conflict – If the printer is not operational or the selected printer profile does not have a heated bed.

Issue a chamber command 

POST /api/printer/chamber

Chamber commands allow setting the temperature and temperature offsets for the printer’s heated chamber. Available commands are:

target

Sets the given target temperature on the printer’s chamber. Additional parameters:

target: Target temperature to set. A value of 0 will turn the heater off.

offset

Sets the given temperature offset on the printer’s chamber. Additional parameters:

offset: Offset to set.

All of these commands may only be sent if the printer is currently operational. Otherwise a 409 Conflict is returned.

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

If no heated chamber is configured for the currently selected printer profile, the resource will return an 409 Conflict.

Requires the CONTROL permission.

Example Target Temperature Request

Set the target temperature for the printer’s heated chamber to 50°C.

POST /api/printer/chamber HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "target",
  "target": 50
}

HTTP/1.1 204 No Content

Example Offset Temperature Request

Set the temperature offset for the heated chamber to -5°C.

POST /api/printer/chamber HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "offset",
  "offset": -5
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – The command to issue, either target or offset.
target (object) – target command: The target temperature to set.
offset (object) – offset command: The offset temperature to set.

Status Codes

204 No Content – No error
400 Bad Request – If target or offset is not a valid number or outside of the supported range, or if the request is otherwise invalid.
409 Conflict – If the printer is not operational or the selected printer profile does not have a heated chamber.

Retrieve the current chamber state 

GET /api/printer/chamber

Retrieves the current temperature data (actual, target and offset) plus optionally a (limited) history (actual, target, timestamp) for the printer’s heated chamber.

It’s also possible to retrieve the temperature history by supplying the history query parameter set to true. The amount of returned history data points can be limited using the limit query parameter.

Returns a 200 OK with a Temperature Response in the body upon success.

If no heated chamber is configured for the currently selected printer profile, the resource will return an 409 Conflict.

Requires the STATUS permission.

Note

If you want tool, bed and chamber temperature information at the same time, take a look at Retrieve the current printer state.

Example

Query the chamber temperature data and also include the temperature history but limit it to two entries.

GET /api/printer/chamber?history=true&limit=2 HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "chamber": {
    "actual": 50.221,
    "target": 70.0,
    "offset": 5
  },
  "history": [
    {
      "time": 1395651928,
      "chamber": {
        "actual": 50.221,
        "target": 70.0
      }
    },
    {
      "time": 1395651926,
      "chamber": {
        "actual": 49.1123,
        "target": 70.0
      }
    }
  ]
}

Query Parameters

history – If set to true (or: yes, y, 1), history information will be included in the response too. If no limit parameter is given, all available temperature history data will be returned.
limit – If set to an integer (n), only the last n data points from the printer’s temperature history will be returned. Will be ignored if history is not enabled.

Status Codes

200 OK – No error
409 Conflict – If the printer is not operational or the selected printer profile does not have a heated chamber.

Issue an SD command 

POST /api/printer/sd

SD commands allow initialization, refresh and release of the printer’s SD card (if available).

Available commands are:

init: Initializes the printer’s SD card, making it available for use. This also includes an initial retrieval of the list of files currently stored on the SD card, so after issuing that command a retrieval of the files on SD card will return a successful result.

Note

If OctoPrint detects the availability of a SD card on the printer during connection, it will automatically attempt to initialize it.
refresh: Refreshes the list of files stored on the printer’s SD card. Will return a 409 Conflict if the card has not been initialized yet (see the init command and SD state).
release: Releases the SD card from the printer. The reverse operation to init. After issuing this command, the SD card won’t be available anymore, hence and operations targeting files stored on it will fail. Will return a 409 Conflict if the card has not been initialized yet (see the init command and SD state).

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

Requires the CONTROL permission.

Example Init Request

Initialize the SD card.

POST /api/printer/sd HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "init"
}

HTTP/1.1 204 No Content

Example Refresh Request

Refresh the file list of the SD card

POST /api/printer/sd HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "refresh"
}

HTTP/1.1 204 No Content

Example Release Request

Release the SD card

POST /api/printer/sd HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "release"
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – The command to issue, either init, refresh or release.

Status Codes

204 No Content – No error
409 Conflict – If a refresh or release command is issued but the SD card has not been initialized (e.g. via init.

Retrieve the current SD state 

GET /api/printer/sd

Retrieves the current state of the printer’s SD card. For this request no authentication is needed.

If SD support has been disabled in OctoPrint’s settings, a 404 Not Found is returned.

Returns a 200 OK with an SD State Response in the body upon success.

Requires the STATUS permission.

Example

Read the current state of the SD card.

GET /api/printer/sd HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "ready": true
}

Status Codes

200 OK – No error
404 Not Found – If SD support has been disabled in OctoPrint’s config.

Retrieve information about the last error 

GET /api/printer/error

Retrieves information about the last error that occurred on the printer.

Returns a 200 OK with an Error Information in the body upon success.

Requires the STATUS permission and MONITOR_TERMINAL to also get access to the last terminal lines associated with the error.

Example

Read the last error that occurred on the printer.

GET /api/printer/error HTTP/1.1
Host: example.com
X-Api-Key: abcdef...

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

{
  "consequence": "emergency",
  "error": "MINTEMP triggered, OMG, kill() called - Not SD printing",
  "faq": "firmware-mintemp",
  "logs": [
    "Send: N2685 G1 X147.748 Y108.411 E627.83763*85",
    "Recv: ok",
    "Send: N2686 G1 X148.522 Y108.286 E627.8963*98",
    "Recv: ok",
    "Send: N2687 G1 X148.866 Y108.174 E627.92338*87",
    "Recv: ok",
    "Send: N2688 G1 X149.494 Y107.868 E627.97566*91",
    "Recv: ok",
    "Send: N2689 G1 X149.731 Y107.779 E627.9946*96",
    "Recv: ok",
    "Send: N2690 G1 X149.69 Y108.032 E628.01378*101",
    "Recv: ok",
    "Send: N2691 G1 X147.252 Y112.252 E628.3785*107",
    "Recv: ok",
    "Send: N2692 G1 X145.082 Y112.253 E628.54089*93",
    "Recv: ok",
    "Recv: Error: MINTEMP triggered, kill() called",
    "Recv: Not SD printing",
    "Changing monitoring state from \"Printing\" to \"Error\""
  ],
  "reason": "firmware"
}

Status Codes

200 OK – No error

Send an arbitrary command to the printer 

POST /api/printer/command

Sends any command to the printer via the serial interface. Should be used with some care as some commands can interfere with or even stop a running print job.

Expects a Arbitrary Command Request as the request’s body.

If successful returns a 204 No Content and an empty body.

Requires the CONTROL permission.

Example for sending a single command

POST /api/printer/command HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "command": "M106"
}

HTTP/1.1 204 No Content

Example for sending multiple commands

POST /api/printer/command HTTP/1.1
Host: example.com
Content-Type: application/json
X-Api-Key: abcdef...

{
  "commands": [
    "M18",
    "M106 S0"
  ]
}

HTTP/1.1 204 No Content

JSON Parameters

command (string) – Single command to send to the printer, mutually exclusive with commands.
commands (string) – List of commands to send to the printer, mutually exclusive with command.

Status Codes

204 No Content – No error

Retrieve custom controls 

GET /api/printer/command/custom

Retrieves the custom controls as configured in config.yaml.

Please refer to the documentation of custom controls on what data structure to expect here.

Returns a 200 OK with an Custom Controls Response in the body upon success.

Requires the CONTROL permission.

Status Codes

200 OK – No error

Data model 

Full State Response 

Name	Multiplicity	Type	Description
`temperature`	0..1	Temperature State	The printer’s temperature state data
`sd`	0..1	SD State	The printer’s sd state data
`state`	0..1	Printer State	The printer’s general state

Temperature State 

Name	Multiplicity	Type	Description
`tool{n}`	0..*	Temperature Data	Current temperature stats for tool n. Enumeration starts at 0 for the first tool. Not included if querying only bed state.
`bed`	0..1	Temperature Data	Current temperature stats for the printer’s heated bed. Not included if querying only tool state or if the currently selected printer profile does not have a heated bed.
`history`	0..1	List of Historic Temperature Datapoint	Temperature history

SD State 

Name	Multiplicity	Type	Description
`ready`	1	Boolean	Whether the SD card has been initialized (`true`) or not (`false`).

Arbitrary Command Request 

Name	Multiplicity	Type	Description
`command`	0..1	String	Single command to send to the printer, mutually exclusive with `commands` and `script`.
`commands`	0..*	Array of String	Multiple commands to send to the printer (in the given order), mutually exclusive with `command` and `script`.
`script`	0..*	String	Name of the GCODE script template to send to the printer, mutually exclusive with `command` and `commands`.
`parameters`	0..1	Map of key value pairs	Key value pairs of parameters to replace in sent commands/provide to the script renderer
`context`	0..1	Map of key value pairs	(only if `script` is set) additional template variables to provide to the script renderer

Custom Controls Response 

Name	Multiplicity	Type	Description
`controls`	0..n	List of custom controls	A list of custom control definitions as defined in `config.yaml`.

Error Information 

Name	Multiplicity	Type	Description
`error`	1	String	The error message, will be empty if no error information is currently present.
`reason`	1	String	The reason for the error, e.g. `firmware` in case of errors triggered by the firmware. Will be empty if no error information is currently present.
`consequence`	0..1	String	The consequence of the error, e.g. `emergency` if an emergency stop and disconnect was triggered, `disconnect` if just a disconnect was triggered, `cancel` if the ongoing print job was cancelled. Will be unset if no consequence was triggered or no error information is currently present.
`faq`	0..1	String	An FAQ id for the error, to be added to `https://faq.octoprint.org/` for a link to the FAQ entry. Will be unset if no FAQ entry is available for the error or no error information is currently present.
`logs`	0..*	List of String	A list of log lines that might be relevant for the error. Will be unset if no error information is currently present or if the requesting user lacks the `MONITOR_TERMINAL` permission.