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
- 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).
- 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. - Appeler l’API — envoyer une requête
POSTavec :- 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
- URL :
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
429accompagnée d’un en-têteRetry-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_snrenvoie400). - 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
coderenvoyé 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éenis_publicn’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ésis_publishetis_offlinene 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_countcorrespond 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 :
- Postman → Importer → sélectionnez le fichier.
- Dans les variables de collection, renseignez
api_keyetdevice_sn. - Définissez
song_id/playlist_idselon les besoins (voir §6). base_urlpointe 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