Settings

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:

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:

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