Printer operations

Warning

This part of the API is still heavily in development, especially anything that has to do with temperature control. If you happen to want to develop against it, you should drop me an email to make sure I can give you a heads-up when something changes.

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

Retrieve the current printer state

GET /api/printer

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

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.

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,
      "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,
      "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:

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 to jog print head on x axis, must be a valid number corresponding to the distance to travel in mm.
  • y: Optional. Amount to jog print head on y axis, must be a valid number corresponding to the distance to travel in mm.
  • z: Optional. Amount to jog print head on z axis, must be a valid number corresponding to the distance to travel in mm.
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.

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

Set the feed rate factor to 105%.

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

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

Set the flow rate factor to 95%.

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

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:

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 tools. Additional parameters:

  • target: Target temperature to set.
offset

Sets the given temperature offset on the printer’s tools. 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.

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.

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

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.

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.

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.

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:

Datamodel

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