System

Note

All system operations require the SYSTEM permission.

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.

Requires the SYSTEM permission.

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",
      "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).",
      "source": "core",
      "resource": "http://example.com/api/system/commands/core/shutdown"
    },
    {
      "action": "reboot",
      "name": "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).",
      "source": "core",
      "resource": "http://example.com/api/system/commands/core/reboot"
    },
    {
      "action": "restart",
      "name": "Restart OctoPrint",
      "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).",
      "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",
    "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).",
    "source": "core",
    "resource": "http://example.com/api/system/commands/core/shutdown"
  },
  {
    "action": "reboot",
    "name": "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).",
    "source": "core",
    "resource": "http://example.com/api/system/commands/core/reboot"
  },
  {
    "action": "restart",
    "name": "Restart OctoPrint",
    "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).",
    "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 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 client command definitions

List of all core commands defined.

custom

0..n

List of client command definitions

List of all custom commands defined in config.yaml.

Client command definitions

A restricted form of the full command definition. For exposing via the API.

Name

Multiplicity

Type

Description

name

1

string

The name of the command to display in the System menu.

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.

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.

Command definition

The full command definition is not available via the API.

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.