# 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:**
```json
{
  "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:**
```json
{
  "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.

```json
{
  "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`](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 |