Printer Administration¶

These endpoints provide access to printer state and printer control. Klippy must be connected to Moonraker to receive a successful response, and in many cases Klippy must be in the ready state.

Most of these endpoints are registered with Moonraker by Klipper. Requests pass from the frontend through Moonraker directly to Klipper. Moonraker does not intervene.

Get Klippy host information¶

HTTP Request

GET /printer/info

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.info",
    "id": 5445
}

Example Response

{
    "state": "ready",
    "state_message": "Printer is ready",
    "hostname": "pi-debugger",
    "klipper_path": "/home/pi/klipper",
    "python_path": "/home/pi/klipper/venv/bin/python",
    "process_id": 275124,
    "user_id": 1000,
    "group_id": 1000,
    "log_file": "/home/pi/printer_data/logs/klippy.log",
    "config_file": "/home/pi/printer_data/config/printer.cfg",
    "software_version": "v0.12.0-85-gd785b396",
    "cpu_info": "4 core ?"
}

Response Specification

Field	Type	Description
`state`	string	Klippy's current state.
`state_message`	string	A message describing Klippy's current state.
`hostname`	string	Hostname of the machine running Klippy.
`klipper_path`	string	Path on disk to the Klipper application.
`python_path`	string	Path on disk to the Python executable running Klippy.
`process_id`	int	The PID of the current Klippy process.
`user_id`	int	The UID of the user the Klippy process belongs to.
`group_id`	int	The GID of the group the Klippy process belongs to.
`log_file`	string	Path on disk to Klipper's log file.
`configfile`	string	Path on disk to Klipper's configuration file.
`software_version`	string	Version of the currently running instance of Klipper.
`cpu_info`	string	A brief description of the host machine's CPU.

Klippy State
State	Description
`ready`	Klippy has initialized and is ready for commands.
`startup`	Klippy is currently in its startup phase.
`error`	Klippy encountered an error during startup.
`shutdown`	Klippy is in the shutdown state. This can be initiated by the user via an emergency stop, or by the software if it encounters a critical error during operation.

Emergency Stop¶

HTTP Request

POST /printer/emergency_stop

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.emergency_stop",
    "id": 4564
}

Note

This endpoint will immediately halt the printer and put it in a "shutdown" state. It should be used to implement an "emergency stop" button and also used if a user enters M112(emergency stop) via a console.

Response

"ok"

Host Restart¶

Requests a Klipper "soft" restart. This will reload the Klippy application and configuration. Connected MCUs will not be reset.

HTTP Request

POST /printer/restart

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.restart",
    "id": 4894
}

Response

"ok"

Firmware Restart¶

Requests a complete Klipper restart. Both the Klippy Application and connected MCUs will be reset.

HTTP Request

POST /printer/firmware_restart

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.firmware_restart",
    "id": 8463
}

Response

"ok"

Printer Status Requests¶

List loaded printer objects¶

Returns a list of Klipper printer objects that are currently loaded. This can be used to determine if a specific object is available for query and/or subscription.

HTTP Request

GET /printer/objects/list

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.objects.list",
    "id": 1454
}

Example Response

{
    "objects": [
        "gcode",
        "webhooks",
        "configfile",
        "mcu",
        "mcu linux",
        "heaters",
        "bme280 chamber",
        "temperature_sensor chamber",
        "filament_switch_sensor extruder_sensor",
        "output_pin sensor_toggle",
        "gcode_move",
        "bed_mesh",
        "exclude_object",
        "temperature_host RPi",
        "temperature_sensor RPi",
        "gcode_macro TURN_OFF_MOTORS",
        "gcode_macro SET_HOMING_CURRENT",
        "temperature_sensor ambient",
        "gcode_macro query_bme280",
        "pause_resume",
        "print_stats",
        "virtual_sdcard",
        "probe",
        "stepper_enable",
        "tmc2130 stepper_x",
        "tmc2130 stepper_y",
        "tmc2130 stepper_z",
        "tmc2130 extruder",
        "heater_bed",
        "heater_fan nozzle_cooling_fan",
        "fan",
        "menu",
        "display_status",
        "output_pin BEEPER_pin",
        "idle_timeout",
        "motion_report",
        "query_endstops",
        "system_stats",
        "manual_probe",
        "toolhead",
        "extruder"
    ]
}

Response Specification

Field	Type	Description
`objects`	[string]	A list Klipper printer objects currently loaded.

Query printer object status¶

Requests the status of a provided set of printer objects.

Tip

See the Printer Objects document for details on the objects available for query.

HTTP Request

POST /printer/objects/query
Content-Type: application/json

{
    "objects": {
        "gcode_move": null,
        "toolhead": ["position", "status"]
    }
}

Using the Query String

The HTTP Request may also be performed using the query string. It is recommended to send the request in the body unless otherwise not possible.

HTTP Request

GET /printer/objects/query?gcode_move&toolhead&extruder=target,temperature

The above will request a status update for all gcode_move and toolhead attributes. Only the temperature and target attributes are requested for the extruder.

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.objects.query",
    "params": {
        "objects": {
            "gcode_move": null,
            "toolhead": ["position", "status"]
        }
    },
    "id": 4654
}

Parameters

Name	Type	Default	Description
`objects`	object	REQUIRED	An object whose key, value pairs represent one or more Printer Object Requests.

Printer Object Request
Key Description	Value Description
The `key`should be an available Klipper printer object.	The `value` specifies the attributes of the object that should be returned. If the value is `null` all attributes will be returned. Alternatively a list of strings specifying the desired attributes can be provided.

Note

If a requested printer object or attribute does not exist then the result will be omitted from the response. No error is returned.

Example Response

{
    "eventtime": 578243.57824499,
    "status": {
        "gcode_move": {
            "absolute_coordinates": true,
            "absolute_extrude": true,
            "extrude_factor": 1,
            "gcode_position": [0, 0, 0, 0],
            "homing_origin": [0, 0, 0, 0],
            "position": [0, 0, 0, 0],
            "speed": 1500,
            "speed_factor": 1
        },
        "toolhead": {
            "position": [0, 0, 0, 0],
            "status": "Ready"
        }
    }
}

Response Specification

Field	Type	Description
`eventtime`	float	The time at which the status was received, according Klipper's monotonic clock.
`status`	object	An object containing the current state of the requested printer objects.

Requests status updates for a set of printer objects. A persistent connection (Websocket or Unix Socket) is required to fulfill this request.

Status updates for subscribed objects are sent asynchronously over the connection. See the notify_status_update notification for details.

Tip

See the Printer Objects document for details on the objects available for subscription.

HTTP Request

Not available

JSON-RPC Request (Websocket and Unix Socket Only)

{
    "jsonrpc": "2.0",
    "method": "printer.objects.subscribe",
    "params": {
        "objects": {
            "gcode_move": null,
            "toolhead": ["position", "status"]
        }
    },
    "id": 5434
}

Parameters

Parameters are identical to the query status parameters. A new request will override a previous request. If objects is set to an empty object then the subscription will be cancelled.

Example Response

{
    "eventtime": 578243.57824499,
    "status": {
        "gcode_move": {
            "absolute_coordinates": true,
            "absolute_extrude": true,
            "extrude_factor": 1,
            "gcode_position": [0, 0, 0, 0],
            "homing_origin": [0, 0, 0, 0],
            "position": [0, 0, 0, 0],
            "speed": 1500,
            "speed_factor": 1,
        },
        "toolhead": {
            "position": [0, 0, 0, 0],
            "status": "Ready"
        }
    }
}

Response Specification

The response spec is identical to the query response specification The response may be used to initialize local state without performing a separate query.

Query Endstops¶

HTTP Request

GET /printer/query_endstops/status

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.query_endstops.status",
    "id": 3456
}

Example Response

{
    "x": "TRIGGERED",
    "y": "open",
    "z": "open"
}

Response Specification

Field	Type	Description
variable	string	The field is the name of the registered endstop. The value will be `open` or `TRIGGERED`.

GCode APIs¶

Run a gcode command¶

Executes a gcode command. Multiple commands may be executed by separating them with a newline (\n). The request returns when the command or series of commands have completed, or when the command results in an error.

Warning

When M112(emergency stop) is requested via this endpoint it will not immediately stop the printer. M112 will be placed on the gcode queue and executed after all previous gcodes are complete. If a frontend detects M112 via user input (such as a console) it should request the /printer/emergency_stop endpoint to immediately halt the printer. This may be done in addition to sending the M112 gcode if desired.

HTTP Request

POST /printer/gcode/script
Content-Type: application/json

{
    "script": "G28"
}

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.gcode.script",
    "params": {
        "script": "G28"
    },
    "id": 7466}

Parameters

Name	Type	Default	Description
`script`	string	REQUIRED	A GCode Command to run. Multiple commands may be specified, separated by a newline (`\n`).

Response

"ok"

Get GCode Help¶

Retrieves a list of registered GCode Command Descriptions. Not all registered GCode commands have a description, so this list should not be treated as an exhaustive list of all supported commands.

HTTP Request

GET /printer/gcode/help

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.gcode.help",
    "id": 4645
}

Example Response

{
    "RESTART": "Reload config file and restart host software",
    "FIRMWARE_RESTART": "Restart firmware, host, and reload config",
    "STATUS": "Report the printer status",
    "HELP": "Report the list of available extended G-Code commands",
    "SAVE_CONFIG": "Overwrite config file and restart",
    "SHUTDOWN_MACHINE": "G-Code macro",
    "SET_GCODE_VARIABLE": "Set the value of a G-Code macro variable",
    "REBOOT_MACHINE": "G-Code macro",
    "UPDATE_DELAYED_GCODE": "Update the duration of a delayed_gcode",
    "TURN_OFF_HEATERS": "Turn off all heaters",
    "TEMPERATURE_WAIT": "Wait for a temperature on a sensor",
    "QUERY_ADC": "Report the last value of an analog pin",
    "QUERY_FILAMENT_SENSOR": "Query the status of the Filament Sensor",
    "SET_FILAMENT_SENSOR": "Sets the filament sensor on/off",
    "SET_PIN": "Set the value of an output pin",
    "BED_MESH_CALIBRATE": "Perform Mesh Bed Leveling",
    "BED_MESH_PROFILE": "Bed Mesh Persistent Storage management",
    "BED_MESH_OUTPUT": "Retrieve interpolated grid of probed z-points",
    "BED_MESH_MAP": "Serialize mesh and output to terminal",
    "BED_MESH_CLEAR": "Clear the Mesh so no z-adjustment is made",
    "BED_MESH_OFFSET": "Add X/Y offsets to the mesh lookup",
    "SET_GCODE_OFFSET": "Set a virtual offset to g-code positions",
    "SAVE_GCODE_STATE": "Save G-Code coordinate state",
    "RESTORE_GCODE_STATE": "Restore a previously saved G-Code state",
    "GET_POSITION": "Return information on the current location of the toolhead",
    "EXCLUDE_OBJECT_START": "Marks the beginning the current object as labeled",
    "EXCLUDE_OBJECT_END": "Marks the end the current object",
    "EXCLUDE_OBJECT": "Cancel moves inside a specified objects",
    "EXCLUDE_OBJECT_DEFINE": "Provides a summary of an object",
    "TURN_OFF_MOTORS": "G-Code macro",
    "CLEAR_PAUSE": "Clears the current paused state without resuming the print",
    "SET_PRINT_STATS_INFO": "Pass slicer info like layer act and total to klipper",
    "SDCARD_RESET_FILE": "Clears a loaded SD File. Stops the print if necessary",
    "SDCARD_PRINT_FILE": "Loads a SD file and starts the print.  May include files in subdirectories.",
    "RESPOND": "Echo the message prepended with a prefix",
    "PROBE": "Probe Z-height at current XY position",
    "QUERY_PROBE": "Return the status of the z-probe",
    "PROBE_CALIBRATE": "Calibrate the probe's z_offset",
    "PROBE_ACCURACY": "Probe Z-height accuracy at current XY position",
    "Z_OFFSET_APPLY_PROBE": "Adjust the probe's z_offset",
    "GET_CURRENT_SKEW": "Report current printer skew",
    "CALC_MEASURED_SKEW": "Calculate skew from measured print",
    "SET_SKEW": "Set skew based on lengths of measured object",
    "SKEW_PROFILE": "Profile management for skew_correction",
    "SET_STEPPER_ENABLE": "Enable/disable individual stepper by name",
    "SET_TMC_FIELD": "Set a register field of a TMC driver",
    "INIT_TMC": "Initialize TMC stepper driver registers",
    "SET_TMC_CURRENT": "Set the current of a TMC driver",
    "DUMP_TMC": "Read and display TMC stepper driver registers",
    "PID_CALIBRATE": "Run PID calibration test",
    "SET_HEATER_TEMPERATURE": "Sets a heater temperature",
    "SET_DISPLAY_TEXT": "Set or clear the display message",
    "SET_DISPLAY_GROUP": "Set the active display group",
    "STEPPER_BUZZ": "Oscillate a given stepper to help id it",
    "FORCE_MOVE": "Manually move a stepper; invalidates kinematics",
    "SET_KINEMATIC_POSITION": "Force a low-level kinematic position",
    "SET_IDLE_TIMEOUT": "Set the idle timeout in seconds",
    "QUERY_ENDSTOPS": "Report on the status of each endstop",
    "SET_VELOCITY_LIMIT": "Set printer velocity limits",
    "MANUAL_PROBE": "Start manual probe helper script",
    "TUNING_TOWER": "Tool to adjust a parameter at each Z height",
    "SET_PRESSURE_ADVANCE": "Set pressure advance parameters",
    "SET_EXTRUDER_ROTATION_DISTANCE": "Set extruder rotation distance",
    "SYNC_EXTRUDER_MOTION": "Set extruder stepper motion queue",
    "SET_EXTRUDER_STEP_DISTANCE": "Set extruder step distance",
    "SYNC_STEPPER_TO_EXTRUDER": "Set extruder stepper",
    "ACTIVATE_EXTRUDER": "Change the active extruder",
    "BASE_PAUSE": "Renamed builtin of 'PAUSE'",
    "BASE_RESUME": "Renamed builtin of 'RESUME'",
    "BASE_CANCEL_PRINT": "Renamed builtin of 'CANCEL_PRINT'",
    "ACCEPT": "Accept the current Z position",
    "ABORT": "Abort manual Z probing tool",
    "TESTZ": "Move to new Z height"
}

Response Specification

Field	Type	Description
variable	string	The field is the name of the registered gcode command. The value is a string containing the associated help descriptions.

Note

As mentioned previously, this list is not exhaustive. Help strings are not available for default gcode handlers such as G1, G28, etc, nor are they available for extended handlers that failed to register a description in Klipper's python source.

Print Job Management¶

Start a print job¶

HTTP Request

POST /printer/print/start?filename=test_print.gcode

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.print.start",
    "params": {
        "filename": "test_print.gcode"
    },
    "id": 4654
}

Parameters

Name	Type	Default	Description
`filename`	string	REQUIRED	The name of the gcode file to print. May be a path relative to the gcode folder.

Response

"ok"

Pause a print job¶

HTTP Request

POST /printer/print/pause

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.print.pause",
    "id": 4564
}

Response

"ok"

Resume a print job¶

HTTP Request

POST /printer/print/resume

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.print.resume",
    "id": 1465
}

Response

"ok"

Cancel a print job¶

HTTP Request

POST /printer/print/cancel

JSON-RPC Request

{
    "jsonrpc": "2.0",
    "method": "printer.print.cancel",
    "id": 2578
}

Response

"ok"

Printer Administration¶

Get Klippy host information¶

Emergency Stop¶

Host Restart¶

Firmware Restart¶

Printer Status Requests¶

List loaded printer objects¶

Query printer object status¶

Subscribe to printer object status updates¶

Query Endstops¶

GCode APIs¶

Run a gcode command¶

Get GCode Help¶

Print Job Management¶

Start a print job¶

Pause a print job¶

Resume a print job¶

Cancel a print job¶