Muro Box Open API — Benutzerhandbuch

Version 1.0 (16. August 2026)

Die Muro Box Open API ermöglicht es Diensten von Drittanbietern und Automatisierungswerkzeugen (zum Beispiel Home Assistant, IFTTT oder Ihren eigenen Skripten), Ihre Muro Box mit einem API-Schlüssel, der mit Ihrem Muro-Box-Konto verknüpft ist, zu steuern – Songs und Playlists abzuspielen, die Wiedergabe zu stoppen, Einstellungen anzupassen und den Katalog für Songs/Playlists zu durchsuchen.

Die API ist auf die Wiedergabe auf Ihrer Muro Box ausgerichtet: Sie gibt niemals MIDI-Dateien oder Download-URLs zurück. Die gesamte Wiedergabe erfolgt auf der Box.

1. Schnellstart

API-Schlüssel erstellen – Öffnen Sie die Muro Box App → Einstellungen → API-Schlüssel → Hinzufügen. Geben Sie dem Schlüssel einen Namen und bestätigen Sie die Eingabe. Der vollständige Schlüssel wird nur einmal angezeigt, und zwar unmittelbar nach der Erstellung – kopieren Sie ihn und bewahren Sie ihn an einem sicheren Ort auf (Sie können ihn später nicht erneut abrufen).
Seriennummer Ihres Geräts ermitteln (device_sn) – sie wird in der App auf der Seite „Geräteeinstellungen“ Ihrer gekoppelten Muro Box angezeigt.
Rufen Sie die API auf – senden Sie eine POST-Anfrage mit:
- URL: https://api.murobox.com/muro_api/v1/... (siehe §3)
- Header: api-key: <your key>
- Header: Content-Type: application/json
- JSON-Body mit den erforderlichen Feldern

Laden Sie die Postman Collection herunter und importieren Sie sie mit einem Klick, um mit dem Testen zu beginnen.

Beispiel (einen Titel abspielen):

curl -X POST https://api.murobox.com/muro_api/v1/devices/play_song/ 
  -H "api-key: YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"device_sn": "YOUR_BOX_SN", "song_id": "YOUR_SONG_ID"}'

Beispielantwort:

{"status": true, "message": "scuuess"}

Werten Sie stets das Feld status aus, um über den Erfolg zu entscheiden – der Text in message ist ausschließlich informativ.

2. Authentifizierung

Element	Wert
Header	`api-key`
Wert	Ihr API-Schlüssel (32 hexadezimale Zeichen, wird bei der Erstellung einmalig angezeigt)
Gehört zu	Ihrem Konto bei Muro Box; er kann die Boxen steuern, die mit diesem Konto gekoppelt sind.

Schlüssel werden auf dem Server ausschließlich als SHA-256-Fingerabdruck gespeichert; der Klartextschlüssel ist nach der Erstellung nicht abrufbar. Halten Sie ihn geheim — wer über den Schlüssel verfügt, kann Ihre Muro Box steuern.
Sie können mehrere Schlüssel erstellen (z. B. einen pro Dienst) und sie in der App umbenennen/löschen (Einstellungen → API-Schlüssel).

Ratenbegrenzung

60 Anfragen pro Minute je API-Schlüssel. Bei Überschreitung erhalten Sie HTTP 429 mit einem Retry-After-Header. Berücksichtigen Sie dieses Kontingent bei der Planung Ihrer Automatisierung.

3. Basis-URL & Endpunkte

Basis-URL: https://api.murobox.com

Alle Endpunkte verwenden POST + JSON-Body.

#	Endpunkt	Zweck	Wichtige Felder
1	`/muro_api/v1/devices/play_song/`	Ein einzelnes Lied abspielen	`device_sn`, `song_id`
2	`/muro_api/v1/devices/play_playlist/`	Eine Wiedergabeliste abspielen	`device_sn`, `playlist_id`
3	`/muro_api/v1/devices/stop_playing/`	Wiedergabe stoppen	`device_sn`
4	`/muro_api/v1/devices/device_settings/`	Einstellungen lesen/aktualisieren	`device_sn` + mindestens eine Einstellung
5	`/muro_api/v1/search/songs/`	Lieder suchen	`keyword`, optional `page`, `lang`
6	`/muro_api/v1/search/packages/`	Wiedergabelisten durchsuchen	`keyword`, optional `page`

4. Endpunktdetails

4.1 Einen Titel abspielen — `POST /muro_api/v1/devices/play_song/`

{
  "device_sn": "YOUR_BOX_SN",
  "song_id": "YOUR_SONG_ID"
}

Feld	Typ	Erforderlich	Beschreibung
`device_sn`	string	ja	die Seriennummer Ihrer Muro Box
`song_id`	string	ja	Titelkennung (siehe §6)

Erfolg: 200 mit {"status": true, "message": "scuuess"}. Fehler: 400 Feld fehlt · 404 Gerät oder Titel nicht gefunden · 403 kein gekoppelter Benutzer oder keine Berechtigung · 429 Ratenlimit erreicht.

4.2 Eine Wiedergabeliste abspielen — `POST /muro_api/v1/devices/play_playlist/`

{
  "device_sn": "YOUR_BOX_SN",
  "playlist_id": "YOUR_PLAYLIST_ID"
}

Feld	Typ	Erforderlich	Beschreibung
`device_sn`	string	Ja	Seriennummer Ihrer Muro Box
`playlist_id`	string	Ja	Kennung der Wiedergabeliste (siehe §6)

Filterung nach Berechtigungen: Die Titel in der Wiedergabeliste werden vor dem Senden an die Muro Box anhand der Berechtigungen Ihres Kontos gefiltert. Eine öffentliche Wiedergabeliste, die private Titel enthält, überträgt daher nur die Titel, die Sie abspielen dürfen:

Öffentliche Wiedergabelisten → öffentliche Titel + Ihre eigenen Titel
Ihre privaten Wiedergabelisten → Ihre Titel + öffentliche Titel anderer Nutzer
Gerät / Urheberrecht / Offline-Wiedergabelisten → Die Box muss an Sie gebunden sein

Erfolg: 200 mit {"status": true, "message": "scuuess"}. Fehler: 400 fehlendes Feld · 404 Gerät oder Wiedergabeliste nicht gefunden · 403 kein Kopplungsbenutzer oder keine Berechtigung · 422 kein abspielbarer Titel in dieser Wiedergabeliste (einschließlich leerer Wiedergabelisten) · 429 Anfragenlimit überschritten.

4.3 Wiedergabe beenden — `POST /muro_api/v1/devices/stop_playing/`

{ "device_sn": "YOUR_BOX_SN" }

Erfolg: 200 mit {"status": true, "message": "scuuess"}. Fehler: 400 · 404 · 403 · 429.

4.4 Geräteeinstellungen — `POST /muro_api/v1/devices/device_settings/`

{
  "device_sn": "YOUR_BOX_SN",
  "motorSpeed": 85,
  "plRandom": false,
  "plMaxTime": 10800,
  "midiPortEnabled": true,
  "bleMidiEnabled": true
}

Feld	Typ	Bereich / Werte	Beschreibung
`device_sn`	string	—	Erforderlich; Seriennummer Ihrer Muro Box
`motorSpeed`	Ganzzahl	50–120 (begrenzt)	Motordrehzahl in Prozent
`plRandom`	Boolescher Wert	`true` / `false` (akzeptiert auch `"true"`/`"false"`, `1`/`0`)	Zufallswiedergabe
`plMaxTime`	Ganzzahl	0–2147483647 Sekunden (begrenzt)	maximale Wiedergabedauer
`midiPortEnabled`	boolean	`true` / `false`	MIDI-Ausgang ein/aus
`bleMidiEnabled`	boolean	`true` / `false`	BLE-MIDI ein/aus

Hinweise:

Mindestens ein Einstellungsfeld ist erforderlich (ein Aufruf, der nur device_sn enthält, gibt 400 zurück).
Nur die oben aufgeführte, für die Automatisierung geeignete Teilmenge wird akzeptiert; andere Einstellungen (Anzeigename, Sommerzeit (DST), Feinabstimmung des Motors, automatische Wiedergabe beim Einschalten usw.) werden von diesem Endpunkt ignoriert.

Erfolg: 200 mit der aktualisierten Teilmenge:

{
  "status": true,
  "data": {
    "motorSpeed": 85,
    "plRandom": false,
    "plMaxTime": 10800,
    "midiPortEnabled": true,
    "bleMidiEnabled": true
  }
}

Fehler: 400 fehlendes device_sn / ungültiges Feld / nichts zu aktualisieren · 404 · 403 · 429.

4.5 Titel suchen — `POST /muro_api/v1/search/songs/`

{
  "keyword": "your keyword",
  "page": 1,
  "lang": "en"
}

Feld	Typ	Erforderlich	Beschreibung
`keyword`	Zeichenkette	ja	Suchbegriff
`page`	Ganzzahl	nein (Standard: 1)	Seitenzahl, 10 Ergebnisse pro Seite; Seiten außerhalb des gültigen Bereichs geben eine leere Liste zurück
`lang`	Zeichenkette	nein	bevorzugte Sprache für `display_name`, z. B. `en`, `zh-hant`, `zh-hans`, `ja`, `ko`, `de`; weglassen, um den Standardnamen zu verwenden

Erfolg: 200

{
  "status": true,
  "data": [
    {
      "song_id": "8bad5d17bccc4b7b9fca727ce2390983",
      "display_name": "Your Song",
      "owner_name": "Artist Name",
      "code": "GI20",
      "visibility": "public"
    }
  ],
  "page": 1,
  "total_page": 3
}

Hinweise:

Es wird niemals eine URL für eine MIDI-Datei zurückgegeben — die Wiedergabe muss über play_song erfolgen.
Es gibt keine standardmäßige Filterung der Melodie-Codes – filtern Sie anhand der zurückgegebenencodeSofern Ihre Automatisierung einen bestimmten Melodientyp benötigt, tragen Sie diesen selbst im Feld ein.
Die Sichtbarkeit wird als dreiwertiger Zustand zurückgegeben.visibilityFeld (public / unlisted / private). Boolescher Wert (Legacy)is_publicist nicht mehr enthalten (entfernt am 17.08.2026).

Fehler: 400 fehlt keyword / ungültig page · 429.

4.6 Wiedergabelisten suchen — `POST /muro_api/v1/search/packages/`

{
  "keyword": "playlist keyword",
  "page": 1
}

Feld	Typ	Erforderlich	Beschreibung
`keyword`	string	ja	Suchbegriff
`page`	integer	nein (Standardwert: 1)	Seitennummer, 10 Ergebnisse je Seite; Seiten außerhalb des gültigen Bereichs liefern eine leere Liste

Erfolg: 200

{
  "status": true,
  "data": [
    {
      "package_id": "485029fa2d3e4fa9ae5db030079c95df",
      "package_name": "My Playlist",
      "owner_name": "Owner",
      "visibility": "public",
      "songs_count": 12
    }
  ],
  "page": 1,
  "total_page": 2
}

Hinweise:

Gibt ausschließlich Metadaten zurück (keine Titelliste innerhalb der Wiedergabeliste).
Die Sichtbarkeit wird im dreiwertigen Feld visibility zurückgegeben. Die veralteten Felder is_publish und is_offline sind nicht mehr enthalten (entfernt am 17.08.2026; Offline-Wiedergabelisten sind an das virtuelle Konto der Spieluhr gebunden).
songs_count ist die Anzahl der Titel, die mit Ihrem Konto abgespielt werden können (gleiche Regel wie in der App).
Die Wiedergabe muss über play_playlist erfolgen.

Fehler: 400 fehlt keyword / ungültig page · 429.

5. Fehlerbehandlung

Bei allen Fehlern wird JSON in derselben Struktur zurückgegeben:

{ "status": false, "message": "..." }

HTTP	Bedeutung	Vorgehensweise
400	fehlendes oder ungültiges Feld	den Request-Body mit §4 abgleichen
404	Gerät / Titel / Playlist nicht gefunden	Überprüfen Sie `device_sn`, `song_id`, `playlist_id`
403	kein Pairing-Benutzer oder keine Berechtigung	Das dem Schlüssel zugeordnete Konto muss mit der Box gekoppelt sein; prüfen Sie bei Wiedergabelisten die Berechtigungsfilterung (§4.2).
422	In dieser Wiedergabeliste ist kein abspielbarer Titel enthalten.	Die Wiedergabeliste ist leer oder enthält keine Titel, die Ihr Konto abspielen kann.
429	Ratenlimit überschritten.	Beachten Sie den `Retry-After`-Header; Kontingent: 60 Anfragen/Minute/Schlüssel

6. Abrufen der `song_id` und der `playlist_id`

Über die App (empfohlen):
- song_id — den Player für einen Song öffnen → ⋯ Menü → Song-ID kopieren.
- playlist_id — die Detailseite einer Playlist öffnen → ⋯ Menü → Playlist-ID kopieren (für alle Playlist-Typen verfügbar, einschließlich Offline-Playlists).
Aus der API: Verwenden Sie die Search-Endpunkte (§4.5 / §4.6), um Bezeichner anhand eines Schlüsselworts nachzuschlagen.

7. Postman-Collection

Eine sofort importierbare Postman-Collection steht unter open-api-postman-collection-prod.json zur Verfügung:

Postman → Import → Datei auswählen.
Tragen Sie in den Collection-Variablen api_key und device_sn ein.
Legen Sie song_id / playlist_id nach Bedarf fest (siehe § 6).
base_url verweist bereits auf die Produktionsumgebung (https://api.murobox.com).

8. Sicherheits- und Betriebshinweise

Behandeln Sie Ihren API-Schlüssel wie ein Passwort – er wird nur einmal angezeigt und kann nicht wiederhergestellt werden.
Für jeden Schlüssel gilt eine Ratenbegrenzung (60/min), und die Nutzung wird auditiert (der Server protokolliert erfolgreiche Aufrufe); Schlüssel, die Sie nicht mehr verwenden, widerrufen Sie in der App.
Die API löst die Wiedergabe ausschließlich auf Muro-Box-Geräten aus, die mit Ihrem Konto gekoppelt sind – sie kann nicht zum Herunterladen von Songs oder MIDI-Dateien verwendet werden.
Wenn Sie umfangreiche Automatisierung planen, halten Sie die Ratenbegrenzung pro Schlüssel ein, oder erstellen Sie mehrere Schlüssel mit jeweils eigenem Kontingent.

Sollten bei der Nutzung Probleme auftreten oder sollten Sie neue Funktionen wünschen, kontaktieren Sie uns bitte per E-Mail unter: support@xx.invalid

Muro Box-Team

Muro Box Open API — Benutzerhandbuch

1. Schnellstart

2. Authentifizierung

Ratenbegrenzung

3. Basis-URL & Endpunkte

4. Endpunktdetails

4.1 Einen Titel abspielen — POST /muro_api/v1/devices/play_song/

4.2 Eine Wiedergabeliste abspielen — POST /muro_api/v1/devices/play_playlist/

4.3 Wiedergabe beenden — POST /muro_api/v1/devices/stop_playing/

4.4 Geräteeinstellungen — POST /muro_api/v1/devices/device_settings/

4.5 Titel suchen — POST /muro_api/v1/search/songs/

4.6 Wiedergabelisten suchen — POST /muro_api/v1/search/packages/

5. Fehlerbehandlung

6. Abrufen der song_id und der playlist_id

7. Postman-Collection

8. Sicherheits- und Betriebshinweise

4.1 Einen Titel abspielen — `POST /muro_api/v1/devices/play_song/`

4.2 Eine Wiedergabeliste abspielen — `POST /muro_api/v1/devices/play_playlist/`

4.3 Wiedergabe beenden — `POST /muro_api/v1/devices/stop_playing/`

4.4 Geräteeinstellungen — `POST /muro_api/v1/devices/device_settings/`

4.5 Titel suchen — `POST /muro_api/v1/search/songs/`

4.6 Wiedergabelisten suchen — `POST /muro_api/v1/search/packages/`

6. Abrufen der `song_id` und der `playlist_id`