Settings¶
Contents
Retrieve current settings¶
-
GET
/api/settings
¶ Retrieves the current configuration of OctoPrint.
Returns a 200 OK with the current settings as a JSON object in the response body.
The data model is similar to what can be found in config.yaml, see below for details.
Save settings¶
-
POST
/api/settings
¶ Saves the provided settings in OctoPrint.
Expects a JSON object with the settings to change as request body. This can be either a full settings tree, or only a partial tree containing only those fields that should be updated.
Returns the currently active settings on success, as part of a 200 OK response.
Requires admin rights.
Example
Only change the UI color to black.
POST /api/settings HTTP/1.1 Host: example.com X-Api-Key: abcdef... Content-Type: application/json { "appearance": { "color": "black" } }
HTTP/1.1 200 OK Content-Type: application/json { "api": { "enabled": true }, "appearance": { "color": "black" } }
Regenerate the system wide API key¶
-
POST
/api/settings/apikey
¶ Generates a new system wide API key.
Does not expect a body. Will return the generated API key as
apikey
property in the JSON object contained in the response body.Requires admin rights.
Status Codes: - 200 OK – No error
- 403 Forbidden – No admin rights
Fetch template data¶
-
GET
/api/settings/templates
¶ Fetch data (currently only the sorting order) of all registered template components in the system.
Use this to get a full list of the identifiers of all UI components provided either by core OctoPrint or any currently active plugins.
Example:
GET /api/settings/templates HTTP/1.1 Host: example.com X-Api-Key: abcdef...
HTTP/1.1 200 OK Content-Type: application/json { "order": { "about": [ { "id": "about", "name": "About OctoPrint" }, { "id": "supporters", "name": "Supporters" }, { "id": "authors", "name": "Authors" }, { "id": "changelog", "name": "Changelog" }, { "id": "license", "name": "OctoPrint License" }, { "id": "thirdparty", "name": "Third Party Licenses" }, { "id": "plugin_pluginmanager", "name": "Plugin Licenses", "plugin_id": "pluginmanager", "plugin_name": "Plugin Manager" } ], "generic": [ { "id": "plugin_announcements", "name": "plugin_announcements", "plugin_id": "announcements", "plugin_name": "Announcement Plugin" } ], "navbar": [ { "id": "settings", "name": "settings" }, { "id": "systemmenu", "name": "systemmenu" }, { "id": "plugin_announcements", "name": "plugin_announcements", "plugin_id": "announcements", "plugin_name": "Announcement Plugin" }, { "id": "login", "name": "login" } ], "plugin_pluginmanager_about_thirdparty": [], "settings": [ { "id": "section_printer", "name": "Printer" }, { "id": "serial", "name": "Serial Connection" }, { "id": "printerprofiles", "name": "Printer Profiles" }, { "id": "temperatures", "name": "Temperatures" }, { "id": "terminalfilters", "name": "Terminal Filters" }, { "id": "gcodescripts", "name": "GCODE Scripts" }, { "id": "section_features", "name": "Features" }, { "id": "features", "name": "Features" }, { "id": "webcam", "name": "Webcam & Timelapse" }, { "id": "accesscontrol", "name": "Access Control" }, { "id": "gcodevisualizer", "name": "GCODE Visualizer" }, { "id": "api", "name": "API" }, { "id": "section_octoprint", "name": "OctoPrint" }, { "id": "server", "name": "Server" }, { "id": "folders", "name": "Folders" }, { "id": "appearance", "name": "Appearance" }, { "id": "plugin_logging", "name": "Logging", "plugin_id": "logging", "plugin_name": "Logging" }, { "id": "plugin_pluginmanager", "name": "Plugin Manager", "plugin_id": "pluginmanager", "plugin_name": "Plugin Manager" }, { "id": "plugin_softwareupdate", "name": "Software Update", "plugin_id": "softwareupdate", "plugin_name": "Software Update" }, { "id": "plugin_announcements", "name": "Announcements", "plugin_id": "announcements", "plugin_name": "Announcement Plugin" }, { "id": "section_plugins", "name": "Plugins" }, { "id": "plugin_action_command_prompt", "name": "Action Command Prompt", "plugin_id": "action_command_prompt", "plugin_name": "Action Command Prompt Support" }, { "id": "plugin_curalegacy", "name": "Cura Legacy", "plugin_id": "curalegacy", "plugin_name": "Cura Legacy" } ], "sidebar": [ { "id": "plugin_printer_safety_check", "name": "Printer Safety Warning", "plugin_id": "printer_safety_check", "plugin_name": "Printer Safety Check" }, { "id": "connection", "name": "Connection" }, { "id": "state", "name": "State" }, { "id": "files", "name": "Files" } ], "tab": [ { "id": "temperature", "name": "Temperature" }, { "id": "control", "name": "Control" }, { "id": "gcodeviewer", "name": "GCode Viewer" }, { "id": "terminal", "name": "Terminal" }, { "id": "timelapse", "name": "Timelapse" } ], "usersettings": [ { "id": "access", "name": "Access" }, { "id": "interface", "name": "Interface" } ], "wizard": [] } }
Requires admin rights.
Warning
This API endpoint is in beta. Things might change. 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 in an backwards incompatible way.
Status Codes: - 200 OK – No error
- 403 Forbidden – No admin rights
Data model¶
The data model on the settings API mostly reflects the contents of
config.yaml. The settings tree
returned by the API contains the following fields, which are directly
mapped from the same fields in config.yaml
unless otherwise noted:
Field | Notes |
---|---|
api.enabled |
|
api.key |
Only maps to api.key in config.yaml if request is sent with admin rights, set to n/a otherwise.
Starting with OctoPrint 1.3.3 setting this field via the API is not possible,
only regenerating it is supported. Setting a custom value is only
possible through config.yaml. |
api.allowCrossOrigin |
|
appearance.name |
|
appearance.color |
|
appearance.colorTransparent |
|
appearance.defaultLanguage |
|
appearance.showFahrenheitAlso |
|
feature.gcodeViewer |
Maps to gcodeViewer.enabled in config.yaml |
feature.sizeThreshold |
Maps to gcodeViewer.sizeThreshold in config.yaml |
feature.mobileSizeThreshold |
Maps to gcodeViewer.mobileSizeThreshold in config.yaml |
feature.temperatureGraph |
|
feature.waitForStart |
|
feature.alwaysSendChecksum |
|
feature.neverSendChecksum |
|
feature.sdSupport |
|
feature.sdRelativePath |
|
feature.sdAlwaysAvailable |
|
feature.swallowOkAfterResend |
|
feature.repetierTargetTemp |
|
feature.externalHeatupDetection |
|
feature.keyboardControl |
|
feature.pollWatched |
|
feature.ignoreIdenticalResends |
|
feature.modelSizeDetection |
|
feature.firmwareDetection |
|
feature.printCancelConfirmation |
|
feature.blockWhileDwelling |
|
folder.uploads |
|
folder.timelapse |
|
folder.timelapseTmp |
Maps to folder.timelapse_tmp in config.yaml |
folder.logs |
|
folder.watched |
|
plugins |
Plugin settings as available from config.yaml and SettingsPlugin implementations |
printer.defaultExtrusionLength |
Maps to printerParameters.defaultExtrusionLength in config.yaml |
scripts.gcode |
Whole subtree of configured GCODE scripts |
serial.port |
Current serial port |
serial.baudrate |
Current serial baudrate |
serial.portOptions |
Available serial ports |
serial.baudrateOptions |
Available serial baudrates |
serial.autoconnect |
|
serial.timeoutConnection |
Maps to serial.timeout.connection in config.yaml |
serial.timeoutDetection |
Maps to serial.timeout.detection in config.yaml |
serial.timeoutCommunication |
Maps to serial.timeout.communication in config.yaml |
serial.timeoutTemperature |
Maps to serial.timeout.temperature in config.yaml |
serial.timeoutTemperatureTargetSet |
Maps to serial.timeout.temperatureTargetSet in config.yaml |
serial.timeoutSdStatus |
Maps to serial.timeout.sdStatus in config.yaml |
serial.log |
|
serial.additionalPorts |
|
serial.additionalBaudrates |
|
serial.longRunningCommands |
|
serial.checksumRequiringCommands |
|
serial.helloCommand |
|
serial.ignoreErrorsFromFirmware |
|
serial.disconnectOnErrors |
|
serial.triggerOkForM29 |
|
serial.supportResendsWIthoutOk |
|
serial.maxTimeoutsIdle |
Maps to serial.maxCommunicationTimeouts.idle in config.yaml |
serial.maxTimeoutsPrinting |
Maps to serial.maxCommunicationTimeouts.printing in config.yaml |
serial.maxTimeoutsLong |
Maps to serial.maxCommunicationTimeouts.long in config.yaml |
server.commands.systemShutdownCommand |
|
server.commands.systemRestartCommand |
|
server.commands.serverRestartCommand |
|
server.diskspace.warning |
|
server.diskspace.critical |
|
system.actions |
Whole subtree taken from config.yaml |
system.events |
Whole subtree taken from config.yaml |
temperature.profiles |
Whole subtree taken from config.yaml |
temperature.cutoff |
|
terminalFilters |
Whole subtree taken from config.yaml |
webcam.streamUrl |
Maps to webcam.stream in config.yaml |
webcam.snapshotUrl |
Maps to webcam.snapshot in config.yaml |
webcam.ffmpegPath |
Maps to webcam.ffmpeg in config.yaml |
webcam.bitrate |
|
webcam.ffmpegThreads |
|
webcam.watermark |
|
webcam.flipH |
|
webcam.flipV |
|
webcam.rotate90 |