logpile/bible-local/03-api.md

# 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.

## 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)

### `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.