HTTP API#

Wszystkie endpointy REST vCLU. Router oparty na frameworku Gin. Odpowiedzi w formacie JSON, chyba że zaznaczono inaczej.

Uwierzytelnianie#

  • Sesja cookie: vclu_session (ważność 7 dni)
  • Tworzenie sesji: POST /login z username/password
  • Usuwanie sesji: GET /logout
  • Domyślnie: jeśli auth nie skonfigurowany, wszystkie ścieżki dostępne

Ścieżki publiczne (bez sesji): /login, /static/*, /wizard, /setup, /api/wizard/*, /api/health

System#

MetodaŚcieżkaAuthOpis
GET/api/healthNieHealth check
POST/api/restartTakRestart procesu vCLU
POST/api/resetTakFactory reset (kasuje wszystkie dane)
GET/metricsTakMetryki Prometheus (format tekstowy)

GET /api/health#

{"status": "ok"}

POST /api/restart#

{"message": "Restarting..."}

POST /api/reset#

{"message": "Factory reset complete", "redirect": "/wizard"}

Urządzenie i konfiguracja#

MetodaŚcieżkaAuthOpis
GET/api/deviceTakInfo o urządzeniu
GET/api/keysTakStatus kluczy (bez wartości)
GET/api/devicesTakLista typów urządzeń
POST/api/settings/saveTakZapisz ustawienia

GET /api/device#

{
  "serialNumber": 2852799910974750602,
  "macAddress": "72:b5:79:eb:92:5c",
  "hardwareType": 19,
  "hardwareVersion": 1,
  "firmwareType": 3,
  "firmwareVersion": 11163050,
  "status": "OK"
}

GET /api/keys#

{
  "hasProjectKey": true,
  "hasIV": true,
  "pin": "00000000"
}

POST /api/settings/save#

Body: obiekt CLUDeviceConfig (JSON)

{"message": "Settings saved"}

Wizard (kreator konfiguracji)#

Wszystkie endpointy /api/wizard/* nie wymagają sesji.

MetodaŚcieżkaOpis
GET/api/wizard/stateBieżący stan wizarda
POST/api/wizard/device-typeUstaw typ urządzenia
POST/api/wizard/moduleDodaj moduł I/O
DELETE/api/wizard/module/:idUsuń moduł
POST/api/wizard/keysKonfiguruj klucze szyfrowania
POST/api/wizard/securityKonfiguruj uwierzytelnianie
POST/api/wizard/finishZakończ konfigurację
GET/api/wizard/om-previewPodgląd om.lua

GET /api/wizard/state#

{
  "deviceTypeId": "clu",
  "deviceTypeName": "CLU",
  "category": "CLU",
  "deviceTypeLocked": false,
  "supportsModules": true,
  "availableDeviceTypes": [],
  "availableModuleTypes": [],
  "modules": [],
  "ioObjects": [],
  "pin": "00000000",
  "broadcastEnabled": false,
  "broadcastKey": "",
  "defaultIV": "",
  "broadcastIV": "",
  "authEnabled": false,
  "authUsername": ""
}

POST /api/wizard/device-type#

Body:

{"deviceTypeId": "clu"}

Odpowiedź:

{"success": true, "deviceType": {...}}

POST /api/wizard/module#

Body:

{"moduleTypeId": "dout8t", "name": "Moduł 1"}

Odpowiedź:

{"module": {...}, "ioObjects": [...]}

POST /api/wizard/keys#

Body:

{
  "pin": "12345678",
  "broadcastEnabled": true,
  "broadcastKey": "base64...",
  "defaultIV": "base64...",
  "broadcastIV": "base64..."
}

POST /api/wizard/security#

Body:

{
  "authEnabled": true,
  "username": "admin",
  "password": "secret"
}

POST /api/wizard/finish#

{"success": true, "device": {...}}

Edytor Lua#

MetodaŚcieżkaAuthOpis
GET/api/editor/treeTakDrzewo plików (main.lua, user.lua, om.lua, modules/)
GET/api/editor/file/*pathTakOdczyt pliku
POST/api/editor/fileTakUtwórz nowy plik w modules/
PUT/api/editor/file/*pathTakZapisz plik
DELETE/api/editor/file/*pathTakUsuń plik modułu
POST/api/editor/folderTakUtwórz folder w modules/
DELETE/api/editor/folder/*pathTakUsuń pusty folder
POST/api/lua/reloadTakPrzeładuj runtime Lua

GET /api/editor/tree#

{
  "system": ["main.lua"],
  "modules": ["modules/my_module.lua"],
  "proxy": ["om.lua", "user.lua"]
}

GET /api/editor/file/*path#

{
  "path": "user.lua",
  "content": "-- user code here",
  "size": 1234,
  "readonly": false
}

PUT /api/editor/file/*path#

Body:

{"content": "-- updated code"}

Odpowiedź:

{"path": "user.lua", "size": 1234}

POST /api/lua/reload#

{"success": true, "message": "Lua runtime reloaded"}

Runtime i wykonanie#

MetodaŚcieżkaAuthOpis
POST/api/clu/executeTakWykonaj skrypt Lua
GET/api/clusTakLista zarejestrowanych CLU

POST /api/clu/execute#

Body:

{
  "targetIP": "",
  "script": "_:info()"
}

Odpowiedź:

{"result": "=== Object Registry ===\n..."}

Pusty targetIP = wykonanie lokalne. Podanie IP = wykonanie na zdalnym CLU.

GET /api/clus#

[
  {"serial": "CLU221000290", "ip": "127.0.0.1", "local": true},
  {"serial": "CLU285279991", "ip": "192.168.0.3", "local": false}
]

Rejestr obiektów#

MetodaŚcieżkaAuthOpis
GET/api/registry/listTakWszystkie obiekty rejestru (JSON)
POST/api/registry/subscribeTakSubskrybuj stany ze zdalnych CLU

GET /api/registry/list#

Zwraca wynik _:toJSON() — tablica JSON obiektów rejestru.

POST /api/registry/subscribe#

{"status": "ok", "result": "Subscribed to 3 CLUs"}

MQTT Broker#

MetodaŚcieżkaAuthOpis
GET/api/mqtt/broker/statsTakStatystyki brokera
GET/api/mqtt/broker/clientsTakPodłączeni klienci MQTT
POST/api/mqtt/broker/saveTakKonfiguracja brokera
GET/api/mqtt/clients/statsTakStatystyki klientów MQTT z Lua
POST/api/mqtt/test/publishTakTest publish MQTT

GET /api/mqtt/broker/stats#

{
  "running": true,
  "port": 1883,
  "clients": 3,
  "subscriptions": 12,
  "messagesReceived": 456,
  "messagesSent": 789
}

POST /api/mqtt/broker/save#

Body:

{
  "enabled": true,
  "port": 1883,
  "wsPort": 8080,
  "username": "mqtt_user",
  "password": "mqtt_pass"
}

POST /api/mqtt/test/publish#

Body:

{"topic": "test/topic", "payload": "hello"}

Home Assistant#

MetodaŚcieżkaAuthOpis
POST/api/ha/discovery/publishTakPublikuj HA Discovery dla wszystkich plików OM
POST/api/ha/commands/enableTakWłącz obsługę komend HA i publikację stanów

POST /api/ha/discovery/publish#

{
  "success": true,
  "published": 15,
  "states": 15,
  "files": 2,
  "errors": []
}

POST /api/ha/commands/enable#

{"success": true, "message": "Command handling enabled"}

HomeKit#

MetodaŚcieżkaAuthOpis
GET/api/homekit/statusTakStatus serwera HomeKit
POST/api/homekit/restartTakRestart serwera HomeKit

GET /api/homekit/status#

{
  "running": true,
  "accessoryCount": 12,
  "pairingAvailable": true
}

Access Control#

MetodaŚcieżkaAuthOpis
GET/api/accessTakLista obiektów z poziomami dostępu
POST/api/accessTakUstaw poziom dostępu
GET/api/access/integrationsTakLista integracji

GET /api/access#

{
  "objects": [
    {
      "path": "CLU.DOUT1",
      "type": "DOUT",
      "name": "Lampa",
      "mqtt": "full",
      "homekit": "full"
    }
  ],
  "integrations": ["mqtt", "homekit"]
}

POST /api/access#

Body:

{
  "path": "CLU.DOUT1",
  "integration": "mqtt",
  "access": "readonly"
}

Odpowiedź:

{
  "success": true,
  "path": "CLU.DOUT1",
  "integration": "mqtt",
  "access": "readonly"
}

Poziomy: full (domyślny), readonly, hidden.

Backup#

MetodaŚcieżkaAuthOpis
POST/api/backup/createTakUtwórz backup ZIP
GET/api/backup/listTakLista backupów
GET/api/backup/download/:filenameTakPobierz plik backup
DELETE/api/backup/:filenameTakUsuń backup

POST /api/backup/create#

{
  "success": true,
  "filename": "backup_20260217_103000.zip",
  "size": 12345,
  "sizeHuman": "12.1 KB"
}

GET /api/backup/list#

{
  "backups": [
    {
      "filename": "backup_20260217_103000.zip",
      "size": 12345,
      "sizeHuman": "12.1 KB",
      "createdAt": "2026-02-17T10:30:00Z"
    }
  ]
}

Pliki OM (zdalne CLU)#

MetodaŚcieżkaAuthOpis
POST/api/om/uploadTakUpload pliku OM (.lua lub diagnostyczny .zip)
GET/api/om/listTakLista zaimportowanych plików OM
GET/api/om/:serialTakSzczegóły pliku OM
DELETE/api/om/:serialTakUsuń plik OM
POST/api/om/regenerateTakRegeneruj pliki proxy

POST /api/om/upload#

Upload multipart (pole file). Obsługuje .lua i .zip (diagnostyczny).

Odpowiedź (.lua):

{
  "success": true,
  "filename": "om_285279991.lua",
  "cluName": "DOM20",
  "cluIP": "192.168.0.3",
  "objectCount": 45,
  "moduleCount": 5
}

Odpowiedź (.zip):

{
  "isZip": true,
  "imported": 2,
  "skipped": 0,
  "results": [...],
  "errors": []
}

GET /api/om/:serial#

{
  "file": {"filename": "om_285279991.lua", "serial": 285279991},
  "clu": {"name": "DOM20", "ip": "192.168.0.3"},
  "modules": [...],
  "objects": [...]
}

Pluginy#

MetodaŚcieżkaAuthOpis
GET/api/plugins/repositoriesTakLista repozytoriów
POST/api/plugins/repositoriesTakDodaj repozytorium
DELETE/api/plugins/repositories/:nameTakUsuń repozytorium
GET/api/plugins/availableTakDostępne pluginy z repozytoriów
GET/api/plugins/installedTakZainstalowane pluginy
POST/api/plugins/installTakInstalacja/aktualizacja pluginu
DELETE/api/plugins/:idTakOdinstaluj plugin
POST/api/plugins/:id/toggleTakWłącz/wyłącz plugin
POST/api/plugins/:id/configTakAktualizuj konfigurację pluginu
GET/api/plugins/:id/schemaTakSchemat konfiguracji pluginu
GET/api/plugins/:id/docTakDokumentacja pluginu

POST /api/plugins/install#

Body:

{
  "id": "weather",
  "fullId": "@vclu/weather",
  "repository": "vCLU Official"
}

POST /api/plugins/:id/toggle#

Body:

{"enabled": true}

POST /api/plugins/:id/config#

Body:

{"config": {"apiKey": "abc123", "city": "Warsaw"}}

Debug i logi#

MetodaŚcieżkaAuthOpis
GET/api/debug/streamTakStrumień logów SSE (Server-Sent Events)
GET/api/debug/sourcesTakDostępne źródła logów
GET/api/debug/historyTakHistoria logów (bufor)
GET/api/debug/statsTakStatystyki strumienia logów

GET /api/debug/stream#

Server-Sent Events — strumień logów w czasie rzeczywistym.

data: {"level":"info","source":"lua","message":"Timer started","timestamp":"..."}

data: {"level":"error","source":"system","message":"Connection failed","timestamp":"..."}

GET /api/debug/history#

{
  "entries": [...],
  "count": 100
}

Statystyki i metryki#

MetodaŚcieżkaAuthOpis
GET/api/statsTakBieżący snapshot metryk
GET/api/stats/timeseriesTakDane historyczne dla wykresów

GET /api/stats#

{
  "timestamp": "2026-02-17T10:30:00Z",
  "uptime": 86400,
  "http": {"requestCount": 1234, "errorCount": 5},
  "lua": {"executeCount": 5678, "errorCount": 2},
  "mqtt": {"messagesIn": 100, "messagesOut": 200},
  "memory": {"alloc": 12345678, "sys": 23456789}
}

GET /api/stats/timeseries#

Query params:

  • since (opcjonalny) — timestamp w ms, od którego zwrócić dane

Strony HTML#

MetodaŚcieżkaOpis
GET/Index — redirect do wizarda lub statusu
GET/loginStrona logowania
POST/loginLogowanie (formularz)
GET/logoutWylogowanie
GET/statusStatus urządzenia
GET/settingsUstawienia
GET/wizardKreator konfiguracji
GET/modulesKonfiguracja modułów
GET/statsStatystyki
GET/toolsNarzędzia deweloperskie
GET/backupZarządzanie backupami
GET/om-filesZarządzanie plikami OM
GET/mqttKonfiguracja MQTT
GET/homekitKonfiguracja HomeKit
GET/accessAccess control
GET/pluginsZarządzanie pluginami
GET/editorEdytor Lua
GET/debugLogi debug

Uwagi#

  • Język: query param ?lang=en|pl, fallback na cookie, potem Accept-Language
  • Middleware: Metrics → Language → Auth
  • Format odpowiedzi błędów:
{"error": "Error description"}
Backward Performance Roadmap Forward