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`

```json
{ "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:

```json
{
  "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`

```json
{
  "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`

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

Response:

```json
{
  "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):**

```json
{
  "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):**

```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):

```json
{ "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`