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

  1. 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).
  2. Het serienummer van uw apparaat vinden (device_sn) — dit wordt weergegeven op de pagina met apparaatinstellingen in de app van uw gekoppelde Muro Box.
  3. 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

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 429 met een Retry-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_sn retourneert 400).
  • 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_song te verlopen.
  • Er is geen standaardfiltering op melodiecode — filter op de geretourneerdecodeVraag 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 visibility met drie toestanden. De verouderde is_publish en is_offline zijn niet langer opgenomen (verwijderd op 17 augustus 2026; offline afspeellijsten zijn gekoppeld aan het virtuele account van de muziekdoos).
  • songs_count is het aantal liedjes dat via uw account kan worden afgespeeld (dezelfde regel als in de app).
  • Het afspelen moet via play_playlist plaatsvinden.

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:

  1. Postman →Import→ Selecteer het bestand.
  2. Vul de collectievariabelen inapi_keyendevice_sn.
  3. Setsong_id / playlist_idIndien nodig (uit §6).
  4. 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