RadioKit Stage — API & integrazioni

🔐 Autenticazione

Due modi di autenticazione:

1. Owner key (per controller admin)

Header X-RK-Key: <LICENSE_KEY> oppure query ?key=.... Usa le chiavi licenza RadioKit (RK-/RKT-/RKR-/RKS-).

2. API key per-room (per Stream Deck / Companion / 3rd party)

Generala in Stage admin → API keys. Header X-RK-API-Key: rks_xxxxxxxx... oppure query ?api_key=.... Una chiave è legata a UNA room, scope read o control.

🎛 Endpoint control (Stream Deck / Companion)

Endpoint pubblico che agisce sul timer corrente della room (il primo running/idle in ordine di posizione).

Opzionale: ?timer_id=<ID> per agire su un timer specifico anziché quello "attivo".

🪝 Webhooks

Quando un evento avviene nella tua room (timer finito, warning, sforamento, ecc.) chiamiamo il tuo URL con un POST JSON.

Payload

{
  "event": "done",           // vedi sezione Eventi
  "room_id": 42,
  "timer_id": 17,
  "ts": "2026-05-14T15:23:45+02:00",
  "data": { ... }     // payload specifico per evento
}

Firma HMAC (opzionale ma consigliato)

Se hai impostato un secret, mandiamo header X-RK-Signature: sha256=<hex>. Verifica con:

# Node.js / Express
const sig = req.headers['x-rk-signature'];
const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(rawBody).digest('hex');
if (sig !== expected) return res.status(401).end();

📡 Eventi disponibili

Configura quali eventi vuoi ricevere come CSV (es. done,warn,over) o * per tutti.

📚 CRUD completo (owner key)

Per integrazioni server-side, gestione completa di room/timer/messaggi/preset:

🎚 Stream Deck — HTTP Request action

Plugin consigliato: HTTP Request (gratuito). Configura ogni tasto così:

• URL: https://radiokit.io/api/stage/?action=control&cmd=start&api_key=rks_TUACHIAVE
• Method: POST
• Headers: X-RK-API-Key: rks_TUACHIAVE (alternativo al query string)

Crea un tasto diverso per ogni comando: start, pause, resume, reset, adjust&delta_sec=60, adjust&delta_sec=-60, finish, message&text=Tempo!.

🎛 Bitfocus Companion

Companion supporta nativamente le HTTP request. Crea un nuovo button con action "HTTP POST" → URL endpoint control con la tua API key. Tutte le combinazioni di feedback sono possibili pollando action=control&cmd=state.

📦 JSON config Companion exportabile in arrivo (q3 2026).

💻 Esempi

curl

# Start del timer attivo
curl -X POST \
  -H "X-RK-API-Key: rks_xxxxxxxxxxxx" \
  "https://radiokit.io/api/stage/?action=control&cmd=start"

# Aggiungi 30 secondi
curl -X POST \
  -H "X-RK-API-Key: rks_xxxxxxxxxxxx" \
  "https://radiokit.io/api/stage/?action=control&cmd=adjust&delta_sec=30"

# Mostra messaggio "Ultimo minuto!" per 10 secondi
curl -X POST \
  -H "X-RK-API-Key: rks_xxxxxxxxxxxx" \
  --data-urlencode "text=Ultimo minuto!" \
  "https://radiokit.io/api/stage/?action=control&cmd=message&auto_hide_sec=10"

JavaScript (browser)

const API_KEY = 'rks_xxxxxxxxxxxx';
async function stage(cmd, params = {}) {
  const qs = new URLSearchParams({ action: 'control', cmd, ...params });
  const r = await fetch(`/api/stage/?${qs}`, {
    method: 'POST', headers: { 'X-RK-API-Key': API_KEY }
  });
  return r.json();
}
// Uso:
stage('start');
stage('adjust', { delta_sec: -60 });
stage('message', { text: '5 minuti!', auto_hide_sec: 8 });

Python

import requests
API_KEY = 'rks_xxxxxxxxxxxx'
URL = 'https://radiokit.io/api/stage/'
def stage(cmd, **kw):
    params = {'action': 'control', 'cmd': cmd, **kw}
    headers = {'X-RK-API-Key': API_KEY}
    return requests.post(URL, params=params, headers=headers).json()

stage('start')
stage('adjust', delta_sec=30)
stage('message', text='Tempo!', auto_hide_sec=5)

Webhook receiver (Node.js)

const express = require('express');
const crypto = require('crypto');
const app = express();
const SECRET = 'mio-secret';

app.post('/rk-stage', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['x-rk-signature'];
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  if (sig !== expected) return res.status(401).end();
  const evt = JSON.parse(req.body);
  console.log('Stage event:', evt.event, evt.timer_id);
  // es. se evt.event === 'done' → manda Slack notification, avvia jingle, ecc.
  res.send('OK');
});

app.listen(3000);