API, Dokumentation und API-Schlüssel

Alles, was das Panel tut, können Sie auch aus Ihrer eigenen Software über die REST-API des Servers erledigen: Kanäle (Start, Stopp, Neustart, Konfiguration), Live-Statistiken, Ereignisse, Zuschauer, Clips, geplante Aufnahmen, Monitorwand, Benutzer. Das Panel selbst nutzt dieselbe API.

Dokumentation und API-Schlüssel gibt es in allen Plänen. Schlüssel nach Bereichen, an IPs gebunden und mit eigenem Limit gehören zur Enterprise-Edition. Verfügbar ab Castreon 1.6.0.

Die Seite API

Verwaltung → API (nur Administratoren) hat zwei Reiter:

• API-Schlüssel — die Schlüssel für Integrationen (Automatisierung, NOC-Werkzeuge, Skripte);
• Dokumentation — die vollständige API-Referenz: jede Operation mit Methode, Pfad, Mindestrolle, Bereich, Parametern, Beispiel für Anfrage und Antwort und einem kopierfertigen curl-Befehl.

openapi.json herunterladen liefert das OpenAPI-3.1-Dokument — direkt importierbar in Postman, Insomnia oder Swagger UI sowie in Codegeneratoren (Python, TypeScript, Go, C#). Es wird aus derselben Tabelle erzeugt, mit der der Server jede Anfrage prüft, und passt daher immer zur installierten Version. Adresse: https://server:port/api/v1/openapi.json (mit API-Schlüssel oder Panel-Sitzung).

Authentifizierung

Jede Anfrage sendet den Schlüssel im Header:

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

Beispiel — Neustart eines Kanals (Schlüssel mit Rolle Operator oder Bereich „Kanalsteuerung“):

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

Fehler haben immer die Form {"error":{"code":"…","message":"…"}} — code ist stabil (für Programme), message ist für Menschen.

API-Schlüssel

Neuer API-Schlüssel → Name, Zugriff, Ablauf. Der Schlüssel wird nur einmal angezeigt — kopieren Sie ihn dann; der Server speichert nur einen Fingerabdruck.

• Nach Rolle (alle Pläne): Der Schlüssel hat die Rechte einer ganzen Rolle — Ansicht, Operator oder Administrator.
• Nach Bereichen (Enterprise): Der Schlüssel darf nur, was die angehakten Bereiche erlauben — Überwachung (Live-Zustand), Konfiguration lesen, Kanalsteuerung (Start, Stopp, Neustart, Playout-Befehle), Konfiguration ändern, Verwaltung. Ein Schlüssel für einen NOC-Bildschirm bekommt nur Überwachung; ein Automatisierungssystem bekommt Kanalsteuerung. Alles außerhalb seiner Bereiche wird mit 403 und dem Code scope abgelehnt, mit dem Namen des fehlenden Bereichs.
• Erlaubte IPs (Enterprise): Der Schlüssel funktioniert nur von den angegebenen Adressen oder Netzen (z. B. 10.20.0.0/24); von anderswo — 403 key_ip.
• Anfragelimit: Jeder Schlüssel hat ein Limit (standardmäßig 600 pro Minute; in Enterprise wählen Sie es). Darüber antwortet der Server mit 429 und Retry-After; jede Antwort enthält X-RateLimit-Limit und X-RateLimit-Remaining.

Die Tabelle zeigt für jeden Schlüssel die letzte Verwendung, die IP-Adresse und die Zahl der Anfragen.

Neuer Schlüssel ohne Unterbrechung der Integrationen

Erneuern auf einem bestehenden Schlüssel erzeugt einen neuen mit denselben Rechten. Wählen Sie, wie lange der alte noch funktioniert — 24 Stunden, 7 Tage oder gar nicht —, damit Sie den Schlüssel in Ihren Integrationen ohne Unterbrechung tauschen können. Widerrufen stoppt einen Schlüssel sofort.

Für den Support

Jede Antwort hat den Header X-Request-ID (Sie können auch einen eigenen senden, um Anfragen mit Ihren Protokollen zu verknüpfen). Wenn eine Anfrage fehlschlägt, geben Sie ihn im Ticket an.

Live-Ereignisse und Webhooks

• GET /api/v1/events ist ein Server-Sent-Events-Strom mit Kanalzustand, Statistiken und Konfigurationsänderungen.
• Benachrichtigungen (siehe Benachrichtigungen) können Warnungen an einen signierten Webhook senden; sein Format ist im OpenAPI-Dokument beschrieben.

Tipps

• Ein Schlüssel pro Integration, mit möglichst wenigen Rechten und, wo möglich, an die IP der Integration gebunden.
• Schlüssel regelmäßig mit Erneuern (mit Überlappung) wechseln und nicht zwischen Systemen wiederverwenden.
• Ältere Schlüssel aus Benutzer → API-Tokens (frühere Versionen) funktionieren unverändert weiter; verwaltet werden sie jetzt auf der Seite API.