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

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/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

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.