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: - 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", "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
orcustom
Status Codes: - 200 OK – No error
- 404 Not Found – If a
source
other thancore
orcustom
is specified.
- source – The source for which to list commands, currently either
Execute a registered system command¶
-
POST
/api/system/commands/
(string: source)/
(string: action)¶ Execute the system command
action
defined insource
.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
orcustom
- 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
andaction
- 500 Internal Server Error – If the command didn’t define a
command
to execute, the command returned a non-zero return code andignore
was nottrue
or some other internal server error occurred
- source – The source for which to list commands, currently either
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. |