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

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