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:¶

200 OK – No error

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:¶

200 OK – No error
404 Not Found – If a source other than core or custom is specified.

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.