System

Note

All system operations require admin rights.

List all registered system commands

GET /api/system/commands

Retrieves all configured system commands.

A 200 OK with a List all response will be returned.

Example

GET /api/system/commands/core HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
HTTP/1.1 200 Ok
Content-Type: application/json

{
  "core": [
    {
      "action": "shutdown",
      "name": "Shutdown",
      "command": "sudo shutdown -h now",
      "confirm": "<strong>You are about to shutdown the system.</strong></p><p>This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
      "async": true,
      "ignore": true,
      "source": "core",
      "resource": "http://example.com/api/system/commands/core/shutdown"
    },
    {
      "action": "reboot",
      "name": "Reboot",
      "command": "sudo reboot",
      "confirm": "<strong>You are about to reboot the system.</strong></p><p>This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
      "async": true,
      "ignore": true,
      "source": "core",
      "resource": "http://example.com/api/system/commands/core/reboot"
    },
    {
      "action": "restart",
      "name": "Restart OctoPrint",
      "command": "sudo service octoprint restart",
      "confirm": "<strong>You are about to restart the OctoPrint server.</strong></p><p>This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
      "async": true,
      "ignore": true,
      "source": "core",
      "resource": "http://example.com/api/system/commands/core/restart"
    }
  ],
  "custom": []
}
Status Codes:

List all registered system commands for a source

GET /api/system/commands/(string: source)

Retrieves the configured system commands for the specified source.

The response will contain a list of command definitions.

Example

GET /api/system/commands/core HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
HTTP/1.1 200 Ok
Content-Type: application/json

[
  {
    "action": "shutdown",
    "name": "Shutdown",
    "command": "sudo shutdown -h now",
    "confirm": "<b>You are about to shutdown the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
    "async": true,
    "ignore": true,
    "source": "core",
    "resource": "http://example.com/api/system/commands/core/shutdown"
  },
  {
    "action": "reboot",
    "name": "Reboot",
    "command": "sudo reboot",
    "confirm": "<b>You are about to reboot the system.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
    "async": true,
    "ignore": true,
    "source": "core",
    "resource": "http://example.com/api/system/commands/core/reboot"
  },
  {
    "action": "restart",
    "name": "Restart OctoPrint",
    "command": "sudo service octoprint restart",
    "confirm": "<b>You are about to restart the OctoPrint server.</b></p><p> This action may disrupt any ongoing print jobs (depending on your printer's controller and general setup that might also apply to prints run directly from your printer's internal storage).",
    "async": true,
    "ignore": true,
    "source": "core",
    "resource": "http://example.com/api/system/commands/core/restart"
  }
]
Parameters:
  • source – The source for which to list commands, currently either core or custom
Status Codes:

Execute a registered system command

POST /api/system/commands/(string: source)/(string: action)

Execute the system command action on defined in source.

Example

Restart OctoPrint via the core system command restart (which is available if the server restart command is configured).

POST /api/system/commands/core/restart HTTP/1.1
Host: example.com
X-Api-Key: abcdef...
HTTP/1.1 204 No Content
Parameters:
  • source – The source for which to list commands, currently either core or custom
  • action – The identifier of the command, action from its definition
Status Codes:
  • 204 No Content – No error
  • 400 Bad Request – If a divider is supposed to be executed or if the request is malformed otherwise
  • 404 Not Found – If the command could not be found for source and action
  • 500 Internal Server Error – If the command didn’t define a command to execute, the command returned a non-zero return code and ignore was not true or some other internal server error occurred

Data model

List all response

Name Multiplicity Type Description
core 0..n List of command definitions List of all core commands defined.
custom 0..n List of command definitions List of all custom commands defined in config.yaml.

Command definition

Name Multiplicity Type Description
name 1 string The name of the command to display in the System menu.
command 1 string The full command line to execute for the command.
action 1 string An identifier to refer to the command programmatically. The special action string divider signifies a divider in the menu.
confirm 0..1 string If present and set, this text will be displayed to the user in a confirmation dialog they have to acknowledge in order to really execute the command.
async 0..1 bool Whether to execute the command asynchronously or wait for its result before responding to the HTTP execution request.
ignore 0..1 bool Whether to ignore the return code of the command’s execution.
source 1 string Source of the command definition, currently either core (for system actions defined by OctoPrint itself) or custom (for custom system commands defined by the user through config.yaml).
resource 1 string The URL of the command to use for executing it.