logpile/docs/bible/03-api.md

03 — API Reference

Conventions

• All endpoints under /api/.
• Request bodies: application/json or multipart/form-data where noted.
• Responses: application/json unless file download.
• Export filenames follow pattern: YYYY-MM-DD (SERVER MODEL) - SERVER SN.<ext>

---

Upload & Data Input

POST /api/upload

Upload a vendor diagnostic archive or a JSON snapshot.

Request: multipart/form-data, field name archive.

Accepted inputs:

• .tar, .tar.gz, .tgz — vendor diagnostic archives
• .txt — plain text files
• JSON file containing a serialized AnalysisResult — re-loaded as-is

Response: 200 OK with parsed result summary, or 4xx/5xx on error.

---

Live Collection

POST /api/collect

Start a live Redfish collection job.

Request body:

{
  "host": "bmc01.example.local",
  "protocol": "redfish",
  "port": 443,
  "username": "admin",
  "auth_type": "password",
  "password": "secret",
  "tls_mode": "insecure"
}

tls_mode values: insecure | verify

Response: 202 Accepted with { "id": "<job-id>" }

GET /api/collect/{id}

Poll job status and progress log.

Response:

{
  "id": "...",
  "status": "running",
  "logs": ["Connecting to BMC...", "Collecting CPUs..."]
}

Status values: queued | running | success | failed | canceled

POST /api/collect/{id}/cancel

Cancel a running job.

---

Data Queries

GET /api/status

Returns source metadata for the current dataset.

{
  "source_type": "api",
  "protocol": "redfish",
  "target_host": "bmc01.example.local",
  "collected_at": "2026-02-10T15:30:00Z"
}

source_type: archive | api

GET /api/config

Returns the full canonical hardware inventory (hardware.devices) plus board info.

GET /api/events

Returns parsed diagnostic events.

GET /api/sensors

Returns sensor readings (temperatures, voltages, fan speeds).

GET /api/serials

Returns serial numbers built from canonical hardware.devices.

GET /api/firmware

Returns firmware versions built from canonical hardware.devices.

GET /api/parsers

Returns list of registered vendor parsers with their identifiers.

---

Export

GET /api/export/csv

Download serial numbers as CSV.

GET /api/export/json

Download full AnalysisResult as JSON (includes raw_payloads).

GET /api/export/reanimator

Download hardware data in Reanimator format for asset tracking integration. See 07-exporters.md for full format spec.

---

Management

DELETE /api/clear

Clear current in-memory dataset.

POST /api/shutdown

Gracefully shut down the server process.

---

Source metadata fields

Fields present in /api/status and /api/config:

Field	Values
source_type	archive | api
protocol	redfish | ipmi (may be empty for archive uploads)
target_host	IP or hostname
collected_at	RFC3339 timestamp