244 lines
6.5 KiB
Markdown
244 lines
6.5 KiB
Markdown
# 03 — API Reference
|
|
|
|
## Conventions
|
|
|
|
- All endpoints are under `/api/`
|
|
- JSON responses are used unless the endpoint downloads a file
|
|
- Async jobs share the same status model: `queued`, `running`, `success`, `failed`, `canceled`
|
|
- Export filenames use `YYYY-MM-DD (MODEL) - SERIAL.<ext>` when board metadata exists
|
|
- Embedded chart viewer routes live under `/chart/` and return HTML/CSS, not JSON
|
|
|
|
## Input endpoints
|
|
|
|
### `POST /api/upload`
|
|
|
|
Uploads one file in multipart field `archive`.
|
|
|
|
Accepted inputs:
|
|
- supported archive/log formats from the parser registry
|
|
- `.json` `AnalysisResult` snapshots
|
|
- raw-export JSON packages
|
|
- raw-export ZIP bundles
|
|
|
|
Result:
|
|
- parses or replays the input
|
|
- stores the result as current in-memory state
|
|
- returns parsed summary JSON
|
|
|
|
Related helper:
|
|
- `GET /api/file-types` returns `archive_extensions`, `upload_extensions`, and `convert_extensions`
|
|
|
|
### `POST /api/collect`
|
|
|
|
Starts a live collection job.
|
|
|
|
Request body:
|
|
|
|
```json
|
|
{
|
|
"host": "bmc01.example.local",
|
|
"protocol": "redfish",
|
|
"port": 443,
|
|
"username": "admin",
|
|
"auth_type": "password",
|
|
"password": "secret",
|
|
"tls_mode": "insecure"
|
|
}
|
|
```
|
|
|
|
Supported values:
|
|
- `protocol`: `redfish` or `ipmi`
|
|
- `auth_type`: `password` or `token`
|
|
- `tls_mode`: `strict` or `insecure`
|
|
|
|
Responses:
|
|
- `202` on accepted job creation
|
|
- `400` on malformed JSON
|
|
- `422` on validation errors
|
|
|
|
Optional request field:
|
|
- `power_on_if_host_off`: when `true`, Redfish collection may power on the host before collection if preflight found it powered off
|
|
- `debug_payloads`: when `true`, collector keeps extra diagnostic payloads and enables extended plan-B retries for slow HGX component inventory branches (`Assembly`, `Accelerators`, `Drives`, `NetworkAdapters`, `PCIeDevices`)
|
|
|
|
### `POST /api/collect/probe`
|
|
|
|
Checks that live API connectivity works and returns host power state before collection starts.
|
|
|
|
Typical request body is the same as `POST /api/collect`.
|
|
|
|
Typical response fields:
|
|
- `reachable`
|
|
- `protocol`
|
|
- `host_power_state`
|
|
- `host_powered_on`
|
|
- `power_control_available`
|
|
- `message`
|
|
|
|
### `GET /api/collect/{id}`
|
|
|
|
Returns async collection job status, progress, timestamps, and accumulated logs.
|
|
|
|
### `POST /api/collect/{id}/cancel`
|
|
|
|
Requests cancellation for a running collection job.
|
|
|
|
### `POST /api/convert`
|
|
|
|
Starts a batch conversion job that accepts multiple files under `files[]` or `files`.
|
|
Each supported file is parsed independently and converted to Reanimator JSON.
|
|
|
|
Response fields:
|
|
- `job_id`
|
|
- `status`
|
|
- `accepted`
|
|
- `skipped`
|
|
- `total_files`
|
|
|
|
### `GET /api/convert/{id}`
|
|
|
|
Returns batch convert job status using the same async job envelope as collection.
|
|
|
|
### `GET /api/convert/{id}/download`
|
|
|
|
Downloads the ZIP artifact produced by a successful convert job.
|
|
|
|
## Read endpoints
|
|
|
|
### `GET /api/status`
|
|
|
|
Returns source metadata for the current dataset.
|
|
If nothing is loaded, response is `{ "loaded": false }`.
|
|
|
|
Typical fields:
|
|
- `loaded`
|
|
- `filename`
|
|
- `vendor`
|
|
- `source_type`
|
|
- `protocol`
|
|
- `target_host`
|
|
- `source_timezone`
|
|
- `collected_at`
|
|
- `stats`
|
|
|
|
### `GET /api/config`
|
|
|
|
Returns the main UI configuration payload, including:
|
|
- source metadata
|
|
- `hardware.board`
|
|
- `hardware.firmware`
|
|
- canonical `hardware.devices`
|
|
- computed specification lines
|
|
|
|
### `GET /api/events`
|
|
|
|
Returns events sorted newest first.
|
|
|
|
### `GET /api/sensors`
|
|
|
|
Returns parsed sensors plus synthesized PSU voltage sensors when telemetry is available.
|
|
|
|
### `GET /api/serials`
|
|
|
|
Returns serial-oriented inventory built from canonical devices.
|
|
|
|
### `GET /api/firmware`
|
|
|
|
Returns firmware-oriented inventory built from canonical devices.
|
|
|
|
### `GET /api/parse-errors`
|
|
|
|
Returns normalized parse and collection issues combined from:
|
|
- Redfish fetch errors in `raw_payloads`
|
|
- raw-export collect logs
|
|
- derived partial-inventory warnings
|
|
|
|
### `GET /api/privacy-scan`
|
|
|
|
Returns the customer-data scan for the current dataset (`models.PrivacyScan`:
|
|
`files_scanned`, `customers[]`, `findings[]`, `summary`), plus `sanitizable`
|
|
(bool) and, when the source already looks de-identified, `sanitized`
|
|
(`{detected, markers, strong, files, evidence}`).
|
|
Returns `{ "loaded": false }` when nothing is loaded. Detection only; see
|
|
`docs/privacy-scan.md`.
|
|
|
|
### `POST /api/sanitize`
|
|
|
|
Builds a de-identified copy of the current uploaded file (customer-data spans
|
|
replaced with same-length neutral fillers, format and timestamps preserved) and
|
|
returns the change preview:
|
|
|
|
```json
|
|
{ "filename": "...", "input_size": 0, "output_size": 0,
|
|
"total_replaced": 0, "changes": [{"path","category","count","sample_before","sample_after"}],
|
|
"skipped_binary": ["member (binary - sanitize manually)"] }
|
|
```
|
|
|
|
`422` when the current dataset is not an uploaded file (live Redfish / snapshot)
|
|
or the format cannot be rebuilt. See `docs/log-sanitization.md`.
|
|
|
|
### `GET /api/sanitize/download`
|
|
|
|
Streams the file produced by the last `POST /api/sanitize`
|
|
(`Content-Disposition: attachment; filename="<original>"`,
|
|
`Content-Type: application/octet-stream`). `404` if none is ready.
|
|
|
|
### `GET /api/parsers`
|
|
|
|
Returns registered parser metadata.
|
|
|
|
### `GET /api/file-types`
|
|
|
|
Returns supported file extensions for upload and batch convert.
|
|
|
|
## Viewer endpoints
|
|
|
|
### `GET /chart/current`
|
|
|
|
Renders the current in-memory dataset as Reanimator HTML using embedded `reanimator/chart`.
|
|
The server first converts the current result to Reanimator JSON, then passes that snapshot to the viewer.
|
|
|
|
### `GET /chart/static/...`
|
|
|
|
Serves embedded `reanimator/chart` static assets.
|
|
|
|
### `GET /topology/current`
|
|
|
|
Renders the current server topology as a standalone static HTML/SVG page in a
|
|
separate browser tab. Rich Bee bundles add DIMM, storage-controller, and NVLink
|
|
edges from persisted diagnostic files. No live commands or polling are used.
|
|
|
|
### `GET /api/topology`
|
|
|
|
Returns the versioned semantic `topology.json` document. It contains nodes and
|
|
relationships, not SVG coordinates.
|
|
|
|
## Export endpoints
|
|
|
|
### `GET /api/export/csv`
|
|
|
|
Downloads serial-number CSV.
|
|
|
|
### `GET /api/export/json`
|
|
|
|
Downloads a raw-export artifact for reopen and re-analysis.
|
|
Current implementation emits a ZIP bundle containing:
|
|
- `raw_export.json`
|
|
- `collect.log`
|
|
- `parser_fields.json`
|
|
- `privacy_report.json` (only when the customer-data scan produced findings)
|
|
- `topology.json` (when topology nodes are available)
|
|
|
|
### `GET /api/export/reanimator`
|
|
|
|
Downloads Reanimator JSON built from the current normalized result.
|
|
|
|
## Management endpoints
|
|
|
|
### `DELETE /api/clear`
|
|
|
|
Clears current in-memory dataset, raw export state, and temporary convert artifacts.
|
|
|
|
### `POST /api/shutdown`
|
|
|
|
Gracefully shuts down the process after responding.
|