API publique

Pilotez la régie depuis n'importe quel outil capable d'appeler une URL : Stream Deck, Bitfocus Companion, raccourcis iOS, curl, Home Assistant… La clé API de votre salle est affichée dans la régie, carte « Lien & QR ».

Principes

• Une URL = une action. Toutes les commandes fonctionnent en simple GET ; les mutations acceptent aussi POST (corps JSON).
• L'authentification est la clé API dans le chemin — aucun en-tête requis, pour rester compatible avec les contrôleurs matériels les plus simples.
• Chaque réponse de commande renvoie l'état complet de la salle, ce qui évite un second appel pour se resynchroniser.
• Limite de débit (v1) : 100 requêtes / minute / clé. Les en-têtes RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset sont présents sur chaque réponse ; au-delà du quota, l'API répond 429.

Version 1 recommandée

Base : /api/v1/{clé}/…. Spec machine complète : openapi.yaml (OpenAPI 3).

Transport et affichage

GET /api/v1/{clé}/start          # démarrer
GET /api/v1/{clé}/pause          # pause (stop = alias de pause)
GET /api/v1/{clé}/reset          # réinitialiser à la durée prévue
GET /api/v1/{clé}/next           # minuteur suivant
GET /api/v1/{clé}/adjust?ms=60000    # +1 min à chaud (−60000 pour retirer)
GET /api/v1/{clé}/blackout?on=1      # écran noir (on=0 pour rallumer)
GET /api/v1/{clé}/onair?on=1         # indicateur ON AIR (on=0 pour éteindre)
GET /api/v1/{clé}/status             # état sans rien modifier

Messages

GET  /api/v1/{clé}/message/set?text=Il reste 5 minutes&flash=1&color=red&bold=1
GET  /api/v1/{clé}/message/clear
POST /api/v1/{clé}/message/set     {"text": "Merci de conclure", "flash": true}

Conducteur (timers)

GET  /api/v1/{clé}/timers                     # liste complète + minuteur actif
POST /api/v1/{clé}/timers                     # créer  {"label": "Keynote", "duration": 1200000}
GET  /api/v1/{clé}/timer/{id}/select          # rendre actif
GET  /api/v1/{clé}/timer/{id}/update?label=…&duration=…&warnAt=…&appearance=…
GET  /api/v1/{clé}/timer/{id}/delete          # supprimer (le dernier est conservé)

État complet

GET /api/v1/{clé}/state

Le serveur est l'horloge de référence. Pour afficher le restant : si running, projetez endAt − serverNow (compensez votre décalage d'horloge avec serverNow) ; sinon utilisez remainingAtPause. Un restant négatif signifie un dépassement. Ne comptez jamais localement seul.

Version 0 rétro-compatibilité

Base : /api/v0/{clé}/{commande}, GET uniquement. Conservée telle quelle pour les configurations Stream Deck existantes :

GET /api/v0/{clé}/start | pause | stop | reset | next
GET /api/v0/{clé}/adjust?ms=60000
GET /api/v0/{clé}/message?text=…&flash=1
GET /api/v0/{clé}/clear_message
GET /api/v0/{clé}/blackout?on=1
GET /api/v0/{clé}/status

Codes d'erreur