Local REST API

The MoBro data service provides a REST API on http://localhost:42069. It is used by the MoBro application and the MoBro Plugin CLI, and is only reachable from the same machine.

This page covers the endpoints that are useful while developing a plugin, e.g. to automate installing a plugin as part of a build script. For everyday use, the CLI is the more convenient option.

note

In all examples, example_plugin stands for the name of the plugin as defined in its mobro_plugin_config.json.
In PowerShell, use curl.exe instead of curl, which is an alias for Invoke-WebRequest.

Plugins

Method	Endpoint	Description
GET	/api/plugins	Lists all installed plugins.
GET	/api/plugins/example_plugin	Returns a single plugin, including its status.
POST	/api/plugins	Installs a new plugin or updates an existing one.
DELETE	/api/plugins/example_plugin	Uninstalls the plugin.
PUT	/api/plugins/example_plugin/reload	Stops the plugin and loads it again from disk.
GET	/api/plugins/example_plugin/settings	Returns the plugin's settings.
PATCH	/api/plugins/example_plugin/settings	Updates some or all of the plugin's settings.
GET	/api/plugins/example_plugin/dependencies	Returns the plugin's external dependencies and status.

Install or Update a Plugin

Send the published .zip file as multipart/form-data with two fields:

• name: the name of the plugin
• zip: the plugin's .zip file (max. 30 MB)

curl.exe -X POST http://localhost:42069/api/plugins -F "name=example_plugin" -F "zip=@example_plugin_0.0.1.zip"

Update Settings

The request body contains the values of the settings fields under custom. Fields that are not included keep their current value, and fields set to null are reset to their default value. The optional enabled flag enables or disables the plugin.

settings.json

{
  "enabled": true,
  "custom": {
    "update_frequency": 5
  }
}

curl.exe -X PATCH http://localhost:42069/api/plugins/example_plugin/settings -H "Content-Type: application/json" -d "@settings.json"

Actions

The actions endpoints let you test the actions of an installed plugin without building a dashboard.

Method	Endpoint	Description
GET	/api/actions?plugin=example_plugin	Lists the actions of the plugin (paged).
GET	/api/actions/{id}	Returns a single action, including its settings fields.
PUT	/api/actions/{id}/invoke	Invokes the action with the given action settings.

Within the REST API, the ID of an action is prefixed with the name of the plugin: the action set_volume of the plugin example_plugin has the ID example_plugin.set_volume. IDs longer than 36 characters are mapped to a hash first, so look up the ID using GET /api/actions if in doubt.

Invoke an Action

The request body contains the values of the action's settings fields under settings. The values are validated against the action's settings fields before the action is invoked.

invocation.json

{
  "settings": {
    "volume": 50
  }
}

curl.exe -X PUT http://localhost:42069/api/actions/example_plugin.set_volume/invoke -H "Content-Type: application/json" -d "@invocation.json"

The action is invoked in the background, so a successful response (204 No Content) doesn't mean the handler succeeded. Check the plugin log for errors. If the plugin isn't running, 409 Conflict is returned.

Logs

Method	Endpoint	Description
GET	/api/logs/plugins/example_plugin	Returns the current log file of the plugin as plain text.
GET	/api/logs/zip	Returns a .zip export containing the log files of all plugins and MoBro.

curl.exe http://localhost:42069/api/logs/plugins/example_plugin
curl.exe -o debug_export.zip http://localhost:42069/api/logs/zip