ome-cockpit/docs/API.md

API reference

Base URL (lab): http://atc-portal01.dell-atc.lan:3090
Internal container port: 8090

All JSON unless noted. No auth middleware in lab build (protect at network edge).

---

Health & fleet

GET /api/health

{ "status": "ok", "updated_at": 1784252683.4, "pulse": 12 }

GET /api/fleet

Full in-memory snapshot:

Field	Description
ome	Appliance name/version/url
summary	totals, connected, offline, watts, samples
devices[]	normalized nodes
subnets[]	/24 aggregates
groups[]	OME groups (names)
models[]	server model counts
alerts[]	recent alert feed
events[]	fleet deltas (incl. device_new/removed)
context	alert_severity, hottest, notifications, …
gpu	latest GPU matrix
pulse	monotonic refresh counter
openwebui_url	companion AI URL

WS /ws/fleet

• On connect: immediate {type:"snapshot", data}
• Then server pushes {type:"snapshot"} / {type:"gpu"} / {type:"error"}
• Client may send any text ping; server mainly broadcasts

---

Devices

GET /api/devices/{device_id}

On-demand OME inventory enrichment.

Response highlights:

{
  "device": { "...fleet node..." },
  "power": { "watts": 320, "avg_watts": 300, "peak_watts": 400, "energy_kwh": 12.3 },
  "inventory_types": ["serverProcessors", "deviceSoftware", "..."],
  "inventory": { "deviceSoftware": [ /* raw OME rows */ ], "...": [] },
  "landscape": {
    "os": [],
    "software": [],
    "firmware": [],
    "drivers": [],
    "applications": [],
    "management": [],
    "licenses": []
  },
  "_ts": 1784252700.0
}

Cached ~300 seconds per device.

---

GPU

GET /api/gpu

Latest GPU sidecar payload (also present on fleet snapshot).

---

Chat & models

GET /api/models

{
  "default": "llama3-70b-gptq",
  "models": [
    { "id": "llama3-70b-gptq", "name": "llama3-70b-gptq", "source": "openwebui|vllm" },
    { "id": "ome-copilot", "name": "OME Copilot", "source": "openwebui" }
  ]
}

POST /api/chat

{
  "message": "List critical systems",
  "history": [{ "role": "user", "content": "..." }],
  "focus_device_id": 50374,
  "model": "llama3-70b-gptq"
}

Response:

{
  "reply": "...",
  "model": "llama3-70b-gptq",
  "backend": "vllm|openwebui",
  "gpu": {},
  "context_bytes": 4104
}

Errors: 502 with upstream detail (context length, auth, etc.).

---

Tickets (Ops desk)

Admins (fixed lab list): jody, laurens (+ names in API).

Method	Path	Purpose
GET	/api/admins	Admin directory
GET	/api/tickets	List tickets
POST	/api/tickets	Create
GET	/api/tickets/{id}	Detail + messages
POST	/api/tickets/{id}/messages	Add note
PATCH	/api/tickets/{id}	status / assignee / priority / accepted_by
DELETE	/api/tickets/{id}	Delete

SQLite file: $COCKPIT_DATA/ops.db (default /data/ops.db).

---

SSH

WS /ws/ssh

Message 1 (client → server):

{
  "type": "auth",
  "host": "10.0.41.50",
  "port": 22,
  "username": "jody",
  "password": "***",
  "cols": 120,
  "rows": 40,
  "term": "xterm-256color"
}

Server control messages: {type:"status|ready|error|pong", message?: string}
Thereafter: raw terminal bytes as WebSocket text.

Client control (optional JSON):

{ "type": "resize", "cols": 100, "rows": 30 }
{ "type": "ping" }

Constraints:

• host must appear as a management IP in the current fleet snapshot
• Max 25 concurrent bridges; max 3 per client IP
• Idle timeout ~30 minutes

GET /api/ssh/sessions

Ops visibility (no secrets):

{ "active": 2, "max": 25, "sessions": [{ "id": "...", "client": "10.0.10.65", "host": "10.0.41.50", "user": "jody", "age_sec": 42 }] }

---

Static assets

Path	File
/	ui/index.html (no-store cache)
/app.js /ops.js /ssh.js /styles.css	UI
/vendor/xterm/*	Terminal library
/dell.png etc.	Branding

---

Environment (settings)

Mapped via pydantic-settings from .env (see .env.example):

OME_URL, OME_USER, OME_PASSWORD, POLL_INTERVAL, OPENWEBUI_URL, OPENWEBUI_EMAIL, OPENWEBUI_PASSWORD, GPU_METRICS_URL, VLLM_URL, VLLM_MODEL, VLLM_MAX_TOKENS, CHAT_SYSTEM_CHARS, COCKPIT_DATA, CORS_ORIGINS

Reports / compliance

Method	Path	Notes
GET	/api/reports/fleet	Fleet matrix + warranty join
GET	/api/reports/firmware	Alias of compliance components
GET	/api/reports/brief	Customer brief payload
GET	/api/compliance	Dell baseline device/component compliance
GET	/api/warranties	WarrantyService dump
GET	/api/baselines	UpdateService baselines
GET	/api/catalogs	UpdateService catalogs
GET	/api/ome/report-defs	ReportService definitions
POST	/api/ome/reports/run	{report_def_id} starts OME report job
GET	/api/ome/reports/{id}/results	Report results when available
GET	/api/ome/jobs	Recent jobs (read-only)
GET	/api/export/{kind}?fmt=csv|json	Downloads
GET	/api/devices/{id}/warranty	Per-device warranty
GET	/api/devices/{id}/compliance	Per-device Dell catalog deltas