Muro Box Open API — Guide d'utilisation

Version 1.0 (16 août 2026)

L'API ouverte Muro Box permet à des services tiers et à des outils d'automatisation (par exemple Home Assistant, IFTTT ou vos propres scripts) de contrôler votre Muro Box : lire des morceaux et des listes de lecture, arrêter la lecture, modifier les paramètres et rechercher dans le catalogue de morceaux/listes de lecture, au moyen d'une clé API liée à votre compte Muro Box.

L'API est conçue autour de la lecture sur votre Muro Box : elle ne renvoie jamais de fichiers MIDI ni d'URL de téléchargement. Toute la lecture s'effectue sur l'appareil.


1. Démarrage rapide

  1. Créer une clé API — Ouvrez l'application Muro Box App → Réglages → Clés API → Ajouter. Donnez un nom à la clé et confirmez. La clé complète est affichée une seule fois, immédiatement après sa création — copiez-la et conservez-la en lieu sûr (vous ne pourrez pas la récupérer par la suite).
  2. Trouver le numéro de série de votre appareil (device_sn) — affiché dans la page des réglages de l'appareil, dans Muro Box App, pour votre Muro Box appairée.
  3. Appeler l’API — envoyer une requête POST avec :
    • URL : https://api.murobox.com/muro_api/v1/... (voir §3)
    • En-tête : api-key: YOUR_API_KEY;your key>
    • En-tête : Content-Type: application/json
    • Corps JSON contenant les champs requis

Téléchargez la collection Postman et importez-la en un clic pour commencer à tester.

Exemple (jouer un morceau) :

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"}'

Exemple de réponse :

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

Analysez toujours le champ status pour décider du succès — le texte message n’est donné qu’à titre informatif.


2. Authentification

Élément Valeur
En-tête api-key
Valeur votre clé API (32 caractères hexadécimaux, affichée une seule fois lors de sa création)
Appartient à votre compte Muro Box ; elle peut contrôler les boîtes appairées à ce compte
  • Les clés ne sont stockées sur le serveur que sous la forme d'une empreinte SHA-256 ; la clé en clair ne peut jamais être récupérée après sa création. Gardez-la secrète — toute personne disposant de la clé peut piloter votre Muro Box.
  • Vous pouvez créer plusieurs clés (par exemple, une par service) et les renommer/supprimer depuis l'application (Paramètres → Clés API).

Limitation du débit

  • 60 requêtes par minute par clé d’API. Lorsque cette limite est dépassée, vous recevez une réponse HTTP 429 accompagnée d’un en-tête Retry-After. Concevez votre automatisation en tenant compte de ce quota.

3. URL de base et points de terminaison

URL de base : https://api.murobox.com

Tous les points de terminaison utilisent POST + un corps JSON.

# Point de terminaison Objectif Champs principaux
1 /muro_api/v1/devices/play_song/ Lire un seul morceau device_sn, song_id
2 /muro_api/v1/devices/play_playlist/ Lire une liste de lecture device_sn, playlist_id
3 /muro_api/v1/devices/stop_playing/ Arrêter la lecture device_sn
4 /muro_api/v1/devices/device_settings/ Lire/mettre à jour les paramètres device_sn + au moins un paramètre
5 /muro_api/v1/search/songs/ Rechercher des morceaux keyword, facultatif page, lang
6 /muro_api/v1/search/packages/ Rechercher des listes de lecture keyword, facultatif page

Détails des points de terminaison

4.1 Jouer un morceau — POST /muro_api/v1/devices/play_song/

{
  "device_sn": "YOUR_BOX_SN",
  "song_id": "YOUR_SONG_ID"
}
Champ Type Obligatoire Description
device_sn string oui numéro de série de votre Muro Box
song_id string oui identifiant du morceau (voir §6)

Succès : 200 avec {"status": true, "message": "scuuess"}. Erreurs : 400 champ manquant · 404 appareil ou morceau introuvable · 403 utilisateur non appairé ou autorisation insuffisante · 429 limite de requêtes atteinte.

4.2 Lire une liste de lecture — POST /muro_api/v1/devices/play_playlist/

{
  "device_sn": "YOUR_BOX_SN",
  "playlist_id": "YOUR_PLAYLIST_ID"
}
Champ Type Obligatoire Description
device_sn chaîne oui numéro de série de votre Muro Box
playlist_id chaîne oui identifiant de la liste de lecture (voir § 6)

Filtrage selon les autorisations : les morceaux de la liste de lecture sont filtrés en fonction des autorisations de votre compte avant d’être envoyés à l’appareil, de sorte qu’une liste de lecture publique contenant des morceaux privés ne transmettra que les morceaux que vous avez l’autorisation de jouer :

  • Listes de lecture publiques → morceaux publics + vos propres morceaux
  • Vos listes de lecture privées → vos morceaux + les morceaux publics des autres utilisateurs
  • Appareil / droits d’auteur / listes de lecture hors ligne → exigent que la boîte soit liée à votre compte

Succès : 200 avec {"status": true, "message": "scuuess"}. Erreurs : 400 champ manquant · 404 appareil ou liste de lecture introuvable · 403 utilisateur non appairé ou sans autorisation · 422 aucun morceau jouable dans cette liste de lecture (y compris les listes de lecture vides) · 429 limite de débit atteinte.

4.3 Arrêter la lecture — POST /muro_api/v1/devices/stop_playing/

{ "device_sn": "YOUR_BOX_SN" }

Succès : 200 avec {"status": true, "message": "scuuess"}. Erreurs : 400 · 404 · 403 · 429.

4.4 Paramètres de l'appareil — POST /muro_api/v1/devices/device_settings/

{
  "device_sn": "YOUR_BOX_SN",
  "motorSpeed": 85,
  "plRandom": false,
  "plMaxTime": 10800,
  "midiPortEnabled": true,
  "bleMidiEnabled": true
}
Champ Type Plage / Valeurs Description
device_sn chaîne de caractères — obligatoire ; numéro de série de votre Muro Box
motorSpeed entier 50–120 (valeur bornée) pourcentage de la vitesse du moteur
plRandom booléen true / false (accepte également "true"/"false", 1/0) lecture aléatoire
plMaxTime entier 0–2147483647 secondes (valeur bornée) durée de lecture maximale
midiPortEnabled booléen true / false Sortie MIDI activée/désactivée
bleMidiEnabled booléen true / false MIDI BLE activé/désactivé

Remarques :

  • Au moins un champ de réglage est requis (un appel ne contenant que device_sn renvoie 400).
  • Seul le sous-ensemble ci-dessus, adapté à l'automatisation, est accepté ; les autres paramètres (nom d'affichage, heure d'été, réglage fin du moteur, lecture automatique à la mise sous tension, …) sont ignorés par ce point de terminaison.

Succès : 200 avec le sous-ensemble mis à jour :

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

Erreurs : 400 absence de device_sn / champ invalide / aucune mise à jour à effectuer · 404 · 403 · 429.

4.5 Recherche de morceaux — POST /muro_api/v1/search/songs/

{
  "keyword": "your keyword",
  "page": 1,
  "lang": "en"
}
Champ Type Requis Description
keyword chaîne de caractères oui mot-clé de recherche
page entier non (valeur par défaut : 1) numéro de page, 10 résultats par page ; les pages hors limites renvoient une liste vide
lang chaîne de caractères non langue préférée pour display_name, p. ex. en, zh-hant, zh-hans, ja, ko, de ; à omettre pour utiliser le nom par défaut

Succès : 200

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

Remarques :

  • Aucune URL de fichier MIDI n'est jamais renvoyée — la lecture doit passer par play_song.
  • Aucun filtrage par code de mélodie n’est appliqué par défaut — filtrez vous-même sur le champ code renvoyé si votre automatisation nécessite un type de mélodie particulier.
  • La visibilité est renvoyée sous la forme d’un champ à trois états visibility (public / unlisted / private). L’ancien champ booléen is_public n’est plus inclus (supprimé le 17 août 2026).

Erreurs : 400 manquant keyword / invalide page · 429.

4.6 Rechercher des listes de lecture — POST /muro_api/v1/search/packages/

{
  "keyword": "playlist keyword",
  "page": 1
}
Champ Type Obligatoire Description
keyword string oui mot-clé de recherche
page entier numéro (1 par défaut) numéro de page, 10 résultats par page ; les numéros de page hors plage renvoient une liste vide

Succès : 200

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

Remarques :

  • Renvoie uniquement les métadonnées (sans liste de morceaux dans la liste de lecture).
  • La visibilité est renvoyée sous la forme du champ à trois états visibility. Les champs hérités is_publish et is_offline ne sont plus inclus (supprimés le 17 août 2026 ; les listes de lecture hors ligne sont liées au compte virtuel de la boîte à musique).
  • songs_count correspond au nombre de morceaux que votre compte peut lire (même règle que dans l'application).
  • La lecture doit passer par play_playlist.

Erreurs : 400 manquant keyword / invalide page · 429.


5. Gestion des erreurs

Toutes les erreurs renvoient un JSON de structure identique :

{ "status": false, "message": "..." }
HTTP Signification Procédure à suivre
400 champ manquant ou invalide vérifier le corps de la requête au regard du §4
404 appareil / morceau / liste de lecture introuvable vérifier device_sn, song_id, playlist_id
403 utilisateur non appairé ou autorisation manquante Le compte associé à la clé doit être appairé avec l'appareil ; pour les listes de lecture, vérifier le filtrage des autorisations (§4.2)
422 Aucun morceau jouable dans cette liste de lecture La liste de lecture est vide ou ne contient aucun morceau que votre compte puisse jouer
429 Limite de débit dépassée Respecter l'en-tête Retry-After ; budget de 60 requêtes/min/clé

6. Obtention de song_id et de playlist_id

  • Depuis l'application (recommandé) :
    • song_id — ouvrez le lecteur d'un morceau → ⋯ menu → Copier l'ID du morceau.
    • playlist_id — ouvrez la page de détail d'une liste de lecture → ⋯ menu → Copier l'ID de la liste de lecture (disponible pour tous les types de listes de lecture, y compris les listes de lecture hors ligne).
  • Depuis l'API : utilisez les points de terminaison Search (§4.5 / §4.6) pour rechercher des identifiants par mot-clé.

7. Collection Postman

Une collection Postman prête à l'importation est disponible à l'adresse open-api-postman-collection-prod.json :

  1. Postman → Importer → sélectionnez le fichier.
  2. Dans les variables de collection, renseignez api_key et device_sn.
  3. Définissez song_id / playlist_id selon les besoins (voir §6).
  4. base_url pointe déjà vers l'environnement de production (https://api.murobox.com).

8. Notes de sécurité et d’exploitation

  • Traitez votre clé d’API comme un mot de passe : elle n’est affichée qu’une seule fois et ne peut être récupérée.
  • Chaque clé est soumise à une limite de débit (60/min) et fait l’objet d’un audit (le serveur journalise les appels réussis) ; révoquez depuis l’application les clés que vous n’utilisez plus.
  • L’API déclenche uniquement la lecture sur les appareils Muro Box appairés à votre compte ; elle ne permet pas de télécharger des morceaux ni des fichiers MIDI.
  • Si vous prévoyez une automatisation intensive, respectez la limite de débit par clé ou créez plusieurs clés pour disposer de quotas indépendants.

 

Si vous rencontrez des problèmes d'utilisation ou si vous avez des demandes de nouvelles fonctionnalités, veuillez nous contacter par courriel à l'adresse suivante : support@xx.invalid

Équipe Muro Box