ControlX Orchestrator API Docs

Basics

Base URL: /api/v1
User-Auth: Authorization: Bearer <token>
Service-Auth: X-API-Key: <key>
Host-Routing läuft über organizations.host_id
X-Host/?host= nur optional als interner Fallback

Response Schema

{
  "data": {},
  "meta": null,
  "schema_version": "1.0",
  "errors": null
}

{
  "data": null,
  "meta": null,
  "schema_version": "1.0",
  "errors": {
    "message": "Validation failed",
    "details": {},
    "code": "VALIDATION_FAILED"
  }
}

Owner/Admin kann per API

Organisationen, Benutzer, Rollen, Passwörter verwalten
Projekte und Projekt-Zugriffe (view/control) verwalten
Server erstellen/ändern/löschen und Rechte pro Server vergeben
Server starten/stoppen/reboot/reinstall/bootdisk ausführen
Hosts, Flavors, Quotas, Limits, API Keys und Billing verwalten

Auth

Login

curl -X POST https://api.bit-controlx.de/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"owner@example.test","password":"Geheim123"}'

Session prüfen

curl -X GET https://api.bit-controlx.de/api/v1/auth/me \
  -H "Authorization: Bearer <TOKEN>"

Organisation

Organisation erstellen

curl -X POST https://api.bit-controlx.de/api/v1/organizations \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Example Org","slug":"example-org","host_id":1,"server_scope":"user"}'

Organisation aktualisieren

curl -X PATCH https://api.bit-controlx.de/api/v1/organizations/1 \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"host_id":1,"server_scope":"organization"}'

Benutzer & Rollen

User erstellen

curl -X POST https://api.bit-controlx.de/api/v1/users \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Testuser","email":"test@controlx.local","password":"Geheim123","organization_id":1,"role":"user"}'

Rolle ändern

curl -X PATCH https://api.bit-controlx.de/api/v1/organizations/1/users/5 \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"role":"admin"}'

Passwort & Entfernen

Passwort setzen

curl -X PUT "https://api.bit-controlx.de/api/v1/users/5/password?organization_id=1" \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"password":"NeuGeheim123","confirmation":"NeuGeheim123"}'

User entfernen

curl -X DELETE "https://api.bit-controlx.de/api/v1/users/5?organization_id=1" \
  -H "Authorization: Bearer <TOKEN>"

Projekte

Projekt erstellen

curl -X POST https://api.bit-controlx.de/api/v1/projects \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"organization_id":1,"name":"Infrastruktur","active":true}'

Projektzugriff vergeben

curl -X POST https://api.bit-controlx.de/api/v1/projects/2/access \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"user_id":5,"permission":"control"}'

Server anlegen

VM mit ISO

curl -X POST https://api.bit-controlx.de/api/v1/servers \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"node":"proxmoxhost","type":"vm","name":"web-01","flavor_id":1,"organization_id":1,"project_id":2,"media_id":"<opaque-media-id>"}'

LXC mit Template

curl -X POST https://api.bit-controlx.de/api/v1/servers \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"node":"proxmoxhost","type":"container","name":"ct-01","flavor_id":1,"organization_id":1,"project_id":2,"template_id":"<opaque-template-id>"}'

Server Betrieb

Aktion

curl -X POST https://api.bit-controlx.de/api/v1/servers/111/action \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"action":"reboot"}'

Reinstall

curl -X POST https://api.bit-controlx.de/api/v1/servers/111/reinstall \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"media_id":"<opaque-media-id>"}'

Server Rechte

Zugriff vergeben

curl -X POST https://api.bit-controlx.de/api/v1/servers/111/access \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"user_id":5,"permission":"view"}'

Zugriff updaten

curl -X PATCH https://api.bit-controlx.de/api/v1/servers/111/access/5 \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"permission":"control"}'

Katalog & Limits

GET /hosts
GET /flavors
GET /quotas
GET /limits/servers?organization_id=1

Host-Felder für Provisioning: lxc_default_storage (empfohlen), optional vm_default_storage.

curl -X GET "https://api.bit-controlx.de/api/v1/limits/servers?organization_id=1" \
  -H "Authorization: Bearer <TOKEN>"

API Keys & Billing

API Key erstellen

curl -X POST https://api.bit-controlx.de/api/v1/api-keys \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Panel Key"}'

Billing

curl -X GET https://api.bit-controlx.de/api/v1/billing/servers/111 \
  -H "Authorization: Bearer <TOKEN>"