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.

Requires the SETTINGS_READ permission.

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 the SETTINGS permission.

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

webcam.watermark

webcam.flipH

webcam.flipV

webcam.rotate90