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:

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

{ "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.