The MuPiBox HTTP API
The box's local HTTP interface – query status, control playback, send announcements and messages, with examples for curl and home automation.
The MuPiBox has a local HTTP API. The touch interface, the Admin interface and the MuPiBox app all use it – and you can use it for your own scripts or home automation. All addresses start with http://<box>:8090/api/ (box = IP address or name, see First boot). Responses are JSON.
Access and security
| Area | Who may access it? |
|---|---|
Player and status (/api/status, /api/command, /api/speak, /api/message …) | any device in the home network, without login |
Administration (/api/admin/…) | only with an Admin login once an Admin password is set |
Network (/api/connectivity/…) | from the home network only with an Admin login |
Home Assistant interface (/api/ha/v1/…) | only via HTTPS (port 8443) with a paired token – used by the integration |
The box blocks write requests coming from other websites in a browser. Scripts such as curl or home automation systems do not send such a browser origin and are allowed.
Querying the status
| Method and path | Returns |
|---|---|
GET /api/health | {"status":"ok","version":"…"} – ideal for reachability checks |
GET /api/status | player state: state (playing, paused, stopped, error), folder, queue, index, position, duration (seconds), volume, max_volume, now_playing (radio title) |
GET /api/info | version, language and the settings interfaces need |
GET /api/library | local library with folders (id, name) and tracks |
GET /api/home | categories and media of the home screen |
GET /api/mupihat/status | battery, charging and voltage with the MuPiHAT |
GET /api/system/metrics | CPU, memory, storage and temperature |
curl http://mupibox.local:8090/api/statusControlling playback
POST /api/command with a JSON object. The action field selects the command:
action | Other fields | Effect |
|---|---|---|
toggle | – | toggle play/pause |
play, pause, stop | – | play, pause, stop |
next, previous | – | next or previous track |
seek | value (seconds) | jump to a position |
volume | value (0 to maximum volume) | set the volume |
volume_delta | value (e.g. 5 or -5) | change the volume relatively |
folder | folder_id | start a folder/audio play from the beginning |
resume | folder_id, item_index | start a folder at a given track (0 = first) |
The folder_id is listed in GET /api/library. The volume is always limited to the configured maximum volume, and parental control settings can restrict API commands too.
# Play/pause
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"toggle"}' http://mupibox.local:8090/api/command
# Volume to 30
curl -X POST -H 'Content-Type: application/json' \
-d '{"action":"volume","value":30}' http://mupibox.local:8090/api/commandAnnouncements and messages
| Method and path | JSON | Effect |
|---|---|---|
POST /api/speak | {"text":"Dinner time!"} | reads the text aloud with the configured voice; music pauses and continues afterwards |
POST /api/message | {"title":"Hello","message":"Bedtime soon","duration_ms":8000} | shows a message on the display (title and duration_ms optional) |
curl -X POST -H 'Content-Type: application/json' \
-d '{"text":"Do not forget to brush your teeth!"}' http://mupibox.local:8090/api/speakThe first announcement of a sentence can take a few seconds because the box generates the speech first; repeated sentences come from the cache.
Errors and responses
Errors come as JSON {"error":"…"} with a matching HTTP status: 400 (bad request), 401 (login required), 403 (not allowed), 409 (not possible right now, e.g. without an Admin password), 503 (service unavailable).