Muro Box Open API — Gebruikershandleiding
Versie 1.0 (16 augustus 2026)
Met de Open API van Muro Box kunnen diensten van derden en automatiseringshulpmiddelen (bijvoorbeeld Home Assistant, IFTTT of uw eigen scripts) uw Muro Box aansturen — nummers en afspeellijsten afspelen, het afspelen stoppen, instellingen aanpassen en de catalogus van nummers/afspeellijsten doorzoeken — met behulp van een API-sleutel die aan uw Muro Box-account is gekoppeld.
De API is opgebouwd rond het afspelen op uw Muro Box: de API retourneert nooit MIDI-bestanden of download-URL's. Het afspelen gebeurt volledig op het apparaat zelf.
1. Snelstart
- Een API-sleutel aanmaken — Open de Muro Box App → Instellingen → API-sleutels → Toevoegen. Geef de sleutel een naam en bevestig. De volledige sleutel wordt slechts één keer weergegeven, direct na het aanmaken — kopieer hem en bewaar hem op een veilige plek (u kunt hem later niet meer opvragen).
- Het serienummer van uw apparaat vinden (
device_sn) — dit wordt weergegeven op de pagina met apparaatinstellingen in de app van uw gekoppelde Muro Box. - Roep de API aan — verstuur een
POST-verzoek met:- URL:
https://api.murobox.com/muro_api/v1/...(zie §3) - Header:
api-key: <your key> - Header:
Content-Type: application/json - JSON-body met de verplichte velden
- URL:
Download de Postman-collectie en importeer deze met één klik om te beginnen met testen.
Voorbeeld (een nummer afspelen):
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"}'
Voorbeeld van een respons:
{"status": true, "message": "scuuess"}
Verwerk altijd het veld status om te bepalen of de bewerking is geslaagd — de tekst van message is uitsluitend informatief.
2. Authenticatie
| Item | Waarde |
|---|---|
| Header | api-key |
| Waarde | uw API-sleutel (32 hexadecimale tekens, eenmalig weergegeven bij het aanmaken) |
| Behoort bij | uw Muro Box-account; de sleutel kan de muziekdozen gekoppeld aan dat account aansturen |
- Sleutels worden op de server uitsluitend opgeslagen als een SHA-256-vingerafdruk; de sleutel in leesbare vorm kan na het aanmaken niet meer worden opgevraagd. Houd deze geheim — iedereen met de sleutel kan uw Muro Box besturen.
- U kunt meerdere sleutels aanmaken (bijvoorbeeld één per dienst) en deze in de Muro Box App hernoemen/verwijderen (Instellingen → API-sleutels).
Snelheidsbeperking
- 60 verzoeken per minuut per API-sleutel. Wanneer deze limiet wordt overschreden, ontvangt u HTTP
429met eenRetry-After-header. Houd bij het ontwerpen van uw automatisering rekening met dit budget.
3. Basis-URL en eindpunten
Basis-URL: https://api.murobox.com
Alle eindpunten gebruiken POST + JSON-body.
| # | Eindpunt | Doel | Belangrijkste velden |
|---|---|---|---|
| 1 | /muro_api/v1/devices/play_song/ |
Eén nummer afspelen | device_sn, song_id |
| 2 | /muro_api/v1/devices/play_playlist/ |
Een afspeellijst afspelen | device_sn, playlist_id |
| 3 | /muro_api/v1/devices/stop_playing/ |
Afspelen stoppen | device_sn |
| 4 | /muro_api/v1/devices/device_settings/ |
Instellingen lezen/bijwerken | device_sn + ten minste één instelling |
| 5 | /muro_api/v1/search/songs/ |
Nummers zoeken | keyword, optioneel page, lang |
| 6 | /muro_api/v1/search/packages/ |
Afspeellijsten zoeken | keyword, optioneel page |
4. Details van het endpoint
4.1 Een nummer afspelen — POST /muro_api/v1/devices/play_song/
{
"device_sn": "YOUR_BOX_SN",
"song_id": "YOUR_SONG_ID"
}
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
device_sn |
string | ja | het serienummer van uw Muro Box |
song_id |
string | ja | identificatie van het nummer (zie §6) |
Succes: 200 met {"status": true, "message": "scuuess"}. Fouten: 400 ontbrekend veld · 404 apparaat of nummer niet gevonden · 403 gebruiker is niet gekoppeld of heeft geen toestemming · 429 verzoeklimiet bereikt.
4.2 Een afspeellijst afspelen — POST /muro_api/v1/devices/play_playlist/
{
"device_sn": "YOUR_BOX_SN",
"playlist_id": "YOUR_PLAYLIST_ID"
}
| Veld | Type | Vereist | Beschrijving |
|---|---|---|---|
device_sn |
string | ja | uw Muro Box-serienummer |
playlist_id |
string | ja | afspeellijst-ID (zie §6) |
Filtering op basis van machtigingen: nummers in de afspeellijst worden vóór verzending naar het apparaat gefilterd op basis van de machtigingen van uw account. Een openbare afspeellijst met privénummers levert daarom alleen de nummers die u mag afspelen:
- Openbare afspeellijsten → openbare nummers + uw eigen nummers
- Uw privéafspeellijsten → uw nummers + openbare nummers van andere gebruikers
- Apparaat / auteursrecht / offline afspeellijsten → hiervoor moet het apparaat aan u gekoppeld zijn
Succes: 200 met {"status": true, "message": "scuuess"}. Fouten: 400 ontbrekend veld · 404 apparaat of afspeellijst niet gevonden · 403 geen koppelingsgebruiker of geen toestemming · 422 geen afspeelbaar nummer in deze afspeellijst (met inbegrip van lege afspeellijsten) · 429 limiet voor verzoekfrequentie bereikt.
4.3 Afspelen stoppen — POST /muro_api/v1/devices/stop_playing/
{ "device_sn": "YOUR_BOX_SN" }
Gelukt: 200 met {"status": true, "message": "scuuess"}. Fouten: 400 · 404 · 403 · 429.
4.4 Apparaatinstellingen — POST /muro_api/v1/devices/device_settings/
{
"device_sn": "YOUR_BOX_SN",
"motorSpeed": 85,
"plRandom": false,
"plMaxTime": 10800,
"midiPortEnabled": true,
"bleMidiEnabled": true
}
| Veld | Type | Bereik / Waarden | Beschrijving |
|---|---|---|---|
device_sn |
string | — | verplicht; het serienummer van uw Muro Box |
motorSpeed |
geheel getal | 50–120 (begrensd) | percentage van de motorsnelheid |
plRandom |
booleaanse waarde | true / false (accepteert ook "true"/"false", 1/0) |
willekeurig afspelen |
plMaxTime |
geheel getal | 0–2147483647 seconden (begrensd) | maximale afspeelduur |
midiPortEnabled |
boolean | true / false |
MIDI-uitvoer aan/uit |
bleMidiEnabled |
boolean | true / false |
BLE MIDI aan/uit |
Opmerkingen:
- Ten minste één instellingsveld is vereist (een aanroep met alleen
device_snretourneert400). - Alleen de hierboven genoemde subset voor automatisering wordt geaccepteerd; andere instellingen (weergavenaam, zomertijd (DST), fijnafstelling van de motor, automatisch afspelen bij inschakelen, …) worden door dit endpoint genegeerd.
Succes: 200 met de bijgewerkte subset:
{
"status": true,
"data": {
"motorSpeed": 85,
"plRandom": false,
"plMaxTime": 10800,
"midiPortEnabled": true,
"bleMidiEnabled": true
}
}
Fouten: 400 ontbrekende device_sn / ongeldig veld / niets om bij te werken · 404 · 403 · 429.
4.5 Nummers zoeken — POST /muro_api/v1/search/songs/
{
"keyword": "your keyword",
"page": 1,
"lang": "en"
}
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
keyword |
tekenreeks | ja | zoekterm |
page |
geheel getal | nee (standaard 1) | paginanummer, 10 resultaten per pagina; pagina's buiten het bereik retourneren een lege lijst |
lang |
tekenreeks | nee | gewenste taal voor display_name, bijvoorbeeld en, zh-hant, zh-hans, ja, ko, de; weglaten voor de standaardnaam |
Succes: 200
{
"status": true,
"data": [
{
"song_id": "8bad5d17bccc4b7b9fca727ce2390983",
"display_name": "Your Song",
"owner_name": "Artist Name",
"code": "GI20",
"visibility": "public"
}
],
"page": 1,
"total_page": 3
}
Opmerkingen:
- Er wordt nooit een URL van een MIDI-bestand geretourneerd — het afspelen dient via
play_songte verlopen. - Er is geen standaardfiltering op melodiecode — filter op de geretourneerde
codeVraag uzelf af of uw automatisering een specifiek type melodie nodig heeft. - Zichtbaarheid wordt geretourneerd als een driestandswaarde.
visibilityveld (public/unlisted/private). Verouderde booleanis_publicis niet langer inbegrepen (verwijderd op 17 augustus 2026).
Fouten: 400 ontbreekt keyword / ongeldig page · 429.
4.6 Afspeellijsten zoeken — POST /muro_api/v1/search/packages/
{
"keyword": "playlist keyword",
"page": 1
}
| Veld | Type | Verplicht | Beschrijving |
|---|---|---|---|
keyword |
string | ja | zoekterm |
page |
geheel getal | no (standaard 1) | paginanummer, 10 resultaten per pagina; pagina's buiten het bereik geven een lege lijst terug |
Succes: 200
{
"status": true,
"data": [
{
"package_id": "485029fa2d3e4fa9ae5db030079c95df",
"package_name": "My Playlist",
"owner_name": "Owner",
"visibility": "public",
"songs_count": 12
}
],
"page": 1,
"total_page": 2
}
Opmerkingen:
- Retourneert alleen metadata (geen nummerlijst in de afspeellijst).
- Zichtbaarheid wordt geretourneerd als het veld
visibilitymet drie toestanden. De verouderdeis_publishenis_offlinezijn niet langer opgenomen (verwijderd op 17 augustus 2026; offline afspeellijsten zijn gekoppeld aan het virtuele account van de muziekdoos). songs_countis het aantal liedjes dat via uw account kan worden afgespeeld (dezelfde regel als in de app).- Het afspelen moet via
play_playlistplaatsvinden.
Fouten: 400 mist keyword / ongeldig: page · 429.
5. Foutafhandeling
Alle fouten worden als JSON met dezelfde structuur geretourneerd:
{ "status": false, "message": "..." }
| HTTP | Betekenis | Afhandeling |
|---|---|---|
| 400 | ontbrekend of ongeldig veld | controleer de body van het verzoek aan de hand van §4 |
| 404 | apparaat / nummer / afspeellijst niet gevonden | controleer device_sn, song_id, playlist_id |
| 403 | geen koppelingsgebruiker, of geen toestemming | het account dat bij de sleutel hoort, moet aan het apparaat zijn gekoppeld; controleer voor afspeellijsten de machtigingsfiltering (§4.2) |
| 422 | deze afspeellijst bevat geen afspeelbaar nummer | de afspeellijst is leeg of bevat geen nummers die uw account kan afspelen |
| 429 | verzoeklimiet overschreden | neem de Retry-After-header in acht; budget van 60 verzoeken/min/sleutel |
6. Verkrijgen van song_id en playlist_id
- Via de app (aanbevolen):
song_id— open de speler voor een nummer →⋯menu → Nummer-ID kopiëren.playlist_id— open de detailpagina van een afspeellijst →⋯menu → Afspeellijst-ID kopiëren (beschikbaar voor alle soorten afspeellijsten, inclusief offline afspeellijsten).
- Via de API: gebruik de Search-endpoints (§4.5 / §4.6) om identifiers aan de hand van een trefwoord op te zoeken.
7. Postman-collectie
Een kant-en-klare Postman-collectie die u direct kunt importeren, is beschikbaar opopen-api-postman-collection-prod.json:
- Postman →Import→ Selecteer het bestand.
- Vul de collectievariabelen in
api_keyendevice_sn. - Set
song_id/playlist_idIndien nodig (uit §6). base_urlverwijst al naar productie (https://api.murobox.com).
8. Beveiligings- en operationele opmerkingen
- Behandel uw API-sleutel als een wachtwoord: deze wordt eenmalig getoond en kan niet worden hersteld.
- Voor elke sleutel geldt een snelheidslimiet (60/min) en elke sleutel wordt geaudit (de server registreert succesvolle aanroepen); trek sleutels die u niet meer gebruikt in via de App.
- De API start alleen het afspelen op muziekdozen die aan uw account zijn gekoppeld — de API kan niet worden gebruikt om nummers of MIDI-bestanden te downloaden.
- Als u intensieve automatisering plant, blijf dan binnen de snelheidslimiet per sleutel of maak meerdere sleutels aan voor afzonderlijke budgetten.
Indien u gebruiksproblemen ondervindt of verzoeken om nieuwe functies heeft, kunt u contact met ons opnemen via e-mail: support@tevofy.com
Muro Box Team