Skip to Content
CubyAPI-Referenz

API-Referenz

Der Cuby-Server läuft standardmäßig auf Port 3847 und bietet eine REST API sowie Socket.IO-Events für Echtzeit-Kommunikation.

REST API

Health

MethodEndpointBeschreibung
GET/api/healthHealth Check — gibt {status: "ok", timestamp} zurück

Authentifizierung

MethodEndpointBeschreibung
POST/api/authLogin mit API Key → Session Cookie
POST/api/auth/tokenAuth-Token erstellen (60s, einmalig)
POST/api/auth/sessionAuth-Token gegen Session Cookie tauschen

Details unter Authentifizierung.

Konfiguration

MethodEndpointBeschreibung
GET/api/configAktuelle Konfiguration inkl. installierter Produkte, API-Key-Status, Operator-Modus und Version
POST/api/config/apikeyAPI Key speichern (UUID v4 Format erforderlich)
GET/api/config/autostartAutostart-Status abfragen
POST/api/config/autostartAutostart aktivieren/deaktivieren — {enabled: true/false}
POST/api/config/trialTrial-Lizenz erstellen (generiert UUID, registriert beim Marketplace)
GET/api/config/validate-apikeyAPI Key gegen Marketplace validieren

Marketplace

MethodEndpointBeschreibung
GET/api/marketplace/productsAlle verfügbaren Produkte mit Installationsstatus und Update-Info
GET/api/marketplace/coursesKurse aus dem Marketplace
GET/api/marketplace/videosAktuelle Videos

Installation

MethodEndpointBeschreibung
POST/api/installInstallation starten — Body: {products: [{productId, alias?}]}
POST/api/install/cancelAusstehende Installation abbrechen — Body: {instanceId}
GET/api/install/status?productId=XInstallationsfortschritt abfragen

Beispiel: Produkt installieren

curl -X POST http://localhost:3847/api/install \ -H "Content-Type: application/json" \ -H "Authorization: Bearer DEIN_API_KEY" \ -d '{"products": [{"productId": "processcube-engine"}]}'

Beispiel: Produkt mit Alias installieren

curl -X POST http://localhost:3847/api/install \ -H "Content-Type: application/json" \ -H "Authorization: Bearer DEIN_API_KEY" \ -d '{"products": [{"productId": "processcube-engine", "alias": "staging"}]}'

Produkte

MethodEndpointBeschreibung
GET/api/products/statusStatus aller laufenden Prozesse
GET/api/products/healthHealth-Check aller Produkte
POST/api/products/start-allAlle konfigurierten Plugins starten

Einzelnes Produkt

MethodEndpointBeschreibung
GET/api/products/:id/statusStatus eines Produkts
GET/api/products/:id/healthHealth-Check eines Produkts
POST/api/products/:id/startProdukt starten
POST/api/products/:id/stopProdukt stoppen
POST/api/products/:id/restartProdukt neustarten
GET/api/products/:id/logs?limit=100In-Memory-Logs (Standard: 100 Zeilen)
GET/api/products/:id/logfile?lines=500Log-Datei (Standard: 500 Zeilen)
POST/api/products/:id/updateAuf neueste Version aktualisieren
DELETE/api/products/:id/uninstallProdukt deinstallieren

Produkt-Konfiguration

MethodEndpointBeschreibung
GET/api/products/:id/has-configPrüfen ob Konfigurationsdialog vorhanden
GET/api/products/:id/configAktuelle Plugin-Konfiguration
POST/api/products/:id/configureKonfiguration speichern und Deployment starten
GET/api/products/:id/config-component.jsReact-Konfigurationskomponente
GET/api/products/:id/has-detailPrüfen ob Detail-Komponente vorhanden
GET/api/products/:id/detail-component.jsReact-Detail-Komponente

Plugin-Routes

MethodEndpointBeschreibung
GET/POST/PUT/DELETE/api/plugins/:instanceId/*Weiterleitung an Plugin-registrierte Routes

ProcessCubes

MethodEndpointBeschreibung
GET/api/processcubesAlle registrierten ProcessCube®-Instanzen (lokal + Sub-Cubies)

Shims

MethodEndpointBeschreibung
GET/api/shim/react.jsReact-Modul für Plugin-Komponenten
GET/api/shim/react-jsx-runtime.jsJSX-Runtime für Plugin-Komponenten
GET/api/shim/react-dom.jsReactDOM für Plugin-Komponenten

Setup

MethodEndpointBeschreibung
POST/api/setup/completeSetup als abgeschlossen markieren

Installations-Status

StatusBeschreibung
installingInstallation läuft
needs_configWartet auf Benutzerkonfiguration
installedErfolgreich installiert
failedInstallation fehlgeschlagen
updatingUpdate läuft

Produkt-Status

StatusBeschreibung
runningProdukt läuft
stoppedManuell gestoppt
crashedAbgestürzt (Auto-Restart folgt)
installingInstallation läuft
installedInstalliert, noch nicht gestartet
updatingUpdate läuft
needs_configWartet auf Konfiguration
failedFehlgeschlagen

Socket.IO Events

Server → Client

EventBeschreibung
install:statusInstallationsfortschritt pro Produkt
products:statusStatus-Änderungen aller Produkte
product:logEinzelne Log-Zeilen eines Produkts
system:statusSystem-Setup-Fortschritt (Node.js-Installation etc.)
processcube:registeredNeue ProcessCube®-Instanz registriert
processcube:unregisteredProcessCube®-Instanz entfernt

Client → Server

EventBeschreibung
subscribe:logsLog-Stream für ein Produkt abonnieren — {productId}
unsubscribe:logsLog-Stream abbestellen — {productId}

Plugin Socket.IO Namespaces

Plugins können eigene Events über dedizierte Namespaces registrieren:

  • Namespace-Pfad: /plugins/<instanceId> (URL-encoded)
  • Auth: Socket.IO-Auth-Middleware wird automatisch angewandt
  • Cleanup: Namespace wird bei Stop/Crash automatisch entfernt

Details unter Plugin-System.


Verbindungsbeispiel

REST API mit curl

# Health Check curl http://localhost:3847/api/health # Config abfragen (mit Auth) curl -H "Authorization: Bearer DEIN_API_KEY" http://localhost:3847/api/config # Produkt starten curl -X POST -H "Authorization: Bearer DEIN_API_KEY" \ http://localhost:3847/api/products/processcube-engine/start # Logs abrufen curl -H "Authorization: Bearer DEIN_API_KEY" \ http://localhost:3847/api/products/processcube-engine/logs?limit=50

Socket.IO mit JavaScript

import { io } from 'socket.io-client'; const socket = io('http://localhost:3847', { auth: { apiKey: 'DEIN_API_KEY' } }); // Status-Updates empfangen socket.on('products:status', (statuses) => { console.log('Produkt-Status:', statuses); }); // Install-Fortschritt empfangen socket.on('install:status', ({ productId, progress, message }) => { console.log(`[${productId}] ${progress}% — ${message}`); }); // Logs abonnieren socket.emit('subscribe:logs', { productId: 'processcube-engine' }); socket.on('product:log', ({ productId, line }) => { console.log(`[${productId}] ${line}`); });