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.

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

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.

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: Optiona. 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/s, 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 movement’s of the axes.

factor: The new factor, percentage as integer or float (percentage divided by 100) between 50 and 200%.

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.

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.

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.

flowrate

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

factor: The new factor, percentage as integer or float (percentage divided by 100) between 75 and 125%.

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 user rights.

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.

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.

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.