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. Server-side multipart limit: 100 MiB.

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 collection job (redfish or ipmi).

Request body:

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

Supported values:

• protocol: redfish | ipmi
• auth_type: password | token
• tls_mode: strict | insecure

Response: 202 Accepted

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "queued",
  "message": "Collection job accepted",
  "created_at": "2026-02-23T12:00:00Z"
}

Validation behavior:

• 400 Bad Request for invalid JSON
• 422 Unprocessable Entity for semantic validation errors (missing/invalid fields)

GET /api/collect/{id}

Poll job status and progress log.

Response:

{
  "job_id": "job_a1b2c3d4e5f6",
  "status": "running",
  "progress": 55,
  "logs": ["..."],
  "created_at": "2026-02-23T12:00:00Z",
  "updated_at": "2026-02-23T12:00:10Z"
}

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.

{
  "loaded": true,
  "filename": "redfish://bmc01.example.local",
  "vendor": "redfish",
  "source_type": "api",
  "protocol": "redfish",
  "target_host": "bmc01.example.local",
  "collected_at": "2026-02-10T15:30:00Z",
  "stats": { "events": 0, "sensors": 0, "fru": 0 }
}

source_type: archive | api

When no dataset is loaded, response is { "loaded": false }.

GET /api/config

Returns source metadata plus:

• hardware.board
• hardware.firmware
• canonical hardware.devices
• computed specification summary lines

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. This endpoint terminates the current process after responding.

---

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