API, documentazione e chiavi API

Tutto ciò che fa il pannello si può fare anche dal tuo software, tramite l'API REST del server: canali (avvio, arresto, riavvio, configurazione), statistiche in tempo reale, eventi, audience, clip, registrazioni programmate, parete di monitoraggio, utenti. Il pannello stesso usa la stessa API.

La documentazione e le chiavi API sono in tutti i piani. Le chiavi per ambiti, legate a IP e con limite scelto sono nell'edizione Enterprise. Disponibile da Castreon 1.6.0.

La pagina API

Amministrazione → API (solo amministratori) ha due schede:

• Chiavi API — le chiavi per le integrazioni (sistemi di automazione, strumenti NOC, script);
• Documentazione — il riferimento completo dell'API: ogni operazione con metodo, percorso, ruolo minimo, ambito, parametri, un esempio di richiesta e di risposta e il comando curl pronto da copiare.

Scarica openapi.json fornisce il documento OpenAPI 3.1 — importalo direttamente in Postman, Insomnia o Swagger UI, oppure nei generatori di codice (Python, TypeScript, Go, C#). È generato dalla stessa tabella con cui il server controlla ogni richiesta, quindi corrisponde sempre alla versione installata. Indirizzo: https://server:porta/api/v1/openapi.json (con una chiave API o la sessione del pannello).

Autenticazione

Ogni richiesta invia la chiave nell'intestazione:

curl -H 'Authorization: Bearer cst_…' https://server:33443/api/v1/channels

Esempio — riavvio di un canale (chiave con ruolo di operatore o con l'ambito «Controllo canali»):

curl -X POST -H 'Authorization: Bearer cst_…' https://server:33443/api/v1/channels/<id>/restart

Gli errori hanno sempre la forma {"error":{"code":"…","message":"…"}} — code è stabile (per i programmi), message è per le persone.

Chiavi API

Nuova chiave API → nome, accesso, scadenza. La chiave viene mostrata una sola volta — copiala subito; il server ne conserva solo un'impronta.

• Per ruolo (tutti i piani): la chiave ha i diritti di un intero ruolo — Visualizzazione, Operatore o Amministratore.
• Per ambiti (Enterprise): la chiave può fare solo ciò che consentono gli ambiti selezionati — Monitoraggio (stato in diretta), Lettura configurazione, Controllo canali (avvio, arresto, riavvio, comandi di playout), Modifica configurazione, Amministrazione. Una chiave per uno schermo NOC riceve solo Monitoraggio; un sistema di automazione riceve Controllo canali. Tutto ciò che è fuori dai suoi ambiti viene rifiutato con 403 e il codice scope, con il nome dell'ambito mancante.
• IP consentiti (Enterprise): la chiave funziona solo dagli indirizzi o dalle reti indicati (es. 10.20.0.0/24); da altrove — 403 key_ip.
• Limite di richieste: ogni chiave ha un limite (600 al minuto di default; in Enterprise lo scegli tu). Oltre, il server risponde 429 con Retry-After; ogni risposta porta X-RateLimit-Limit e X-RateLimit-Remaining.

La tabella mostra per ogni chiave l'ultimo uso, l'indirizzo IP e il numero di richieste.

Una nuova chiave senza fermare le integrazioni

Rinnova su una chiave esistente ne crea un'altra con gli stessi diritti. Scegli per quanto la vecchia continua a funzionare — 24 ore, 7 giorni o per niente — così puoi cambiare la chiave nelle integrazioni senza interruzioni. Revoca ferma una chiave subito.

Per il supporto

Ogni risposta ha l'intestazione X-Request-ID (puoi inviarne anche uno tuo, per collegare le richieste ai tuoi log). Se una richiesta non va, indicalo nel ticket.

Eventi in tempo reale e webhook

• GET /api/v1/events è un flusso Server-Sent Events con lo stato dei canali, le statistiche e le modifiche di configurazione.
• Le notifiche (vedi Notifiche) possono inviare gli avvisi a un webhook firmato; il suo formato è descritto nel documento OpenAPI.

Consigli

• Una chiave per integrazione, con meno diritti possibile e, dove puoi, legata all'IP dell'integrazione.
• Cambia le chiavi periodicamente con Rinnova (con sovrapposizione) e non riutilizzarle tra sistemi diversi.
• Le chiavi più vecchie da Utenti → Token API (versioni precedenti) continuano a funzionare; ora si gestiscono dalla pagina API.