Internal API

The boot-unlock check. The kiosk boots into a hard lock and calls this once it is online; only an affirmative allow unlocks the UI, for that boot. It applies the same decision ladder as check-in but is unmetered — booting isn't wiping, so it never touches quota. On allow it only updates the token's last_seen_at (a heartbeat).

Request body

Responses

• 200 — allowed. account is the account's display name; quota_remaining is null when the token is unlimited.
• 403 — denied, with a reason from the table above. Fires the wipe_session_blocked webhook with phase "verify".
• 404 — unknown token or mismatched account_id.

Note the asymmetry with check-in: verify returns account, validate returns job_id — never both.

The metered pre-wipe check-in. Same request body and same decision ladder as verify, with two differences: an allow atomically increments the token's use_count (a single-writer SQL increment, so concurrent check-ins can't double-spend quota), and the response carries a fresh job_id — the UUID that ties the eventual wipe result back to this check-in and makes wipe-result submission idempotent.

quota_remaining is computed after the increment; null means unlimited.

This is the fail-closed gate: a deny, an unprovisioned stick, or any network failure blocks the wipe. On allow it fires the wipe_session_ready webhook; on deny, wipe_session_blocked with phase "checkin".

Request body

Responses

• 200 — allowed, quota consumed, job_id issued.
• 403 / 404 — same shapes and reasons as verify (phase "checkin" on the blocked webhook).

The once-per-boot hardware report: the complete serialized fingerprint plus internal storage for the machine the kiosk booted on. This is what populates /webapp/inventory.

Upsert semantics

Assets are upserted one row per physical machine per account, keyed by hardware_uid = [system.uuid, system.serial].join("/") (falling back to record_id when DMI identity is missing). The first sighting records who reported it (user, license token, ISO download) and first_seen_at; every subsequent boot updates record_id, engine_version, the full fingerprint document, and last_booted_at.

Alongside the raw document, a set of promoted columns is refreshed on every boot for grids and the public API: manufacturer, model, serial_number, board_model/board_serial, asset_tag, bios_version, tpm_version, firmware_mode, secure_boot, cpu_model/cpu_cores/cpu_threads, memory_total_bytes, gpu, storage_summary, storage_serials, and battery_health_pct (the minimum across batteries).

Fires the asset_reported webhook on the machine's first boot only — repeat boots update the stored asset silently.

Request body

Responses

• 201 — upserted (created or refreshed).
• 403 — {"error": "token revoked"} (or suspended/disabled).
• 404 — {"error": "unknown token"}.
• 422 — {"error": "missing record_id or fingerprint"}.

Attaches the kiosk operator's free-text notes to an already-reported asset, addressed by the boot's record_id. Fires no webhook.

Request body

Responses

• 200 — saved.
• 403 — token not active.
• 404 — {"error": "unknown token"} or {"error": "unknown asset"} (the boot's asset report must land first).

Records the kiosk's hardware test results against the asset. Each submission replaces the whole snapshot — send the complete set every time, not a delta. Fires the hardware_tests_completed webhook.

Wire ids and statuses

tests is an object keyed by wire id, each value { "status": ..., "detail": ... }:

Request body

Responses

• 200 — snapshot replaced.
• 403 / 404 — as on notes.
• 422 — {"error": "invalid tests"}.

One POST per erased drive, carrying the full evidence of the wipe. The endpoint is idempotent on job_id: the first receipt creates the record and returns 201; a re-POST with the same job_id returns 200 with the existing record and fires nothing again. That makes retries safe — the engine can resend after a network blip without duplicating results, quota, or certificates.

On first receipt only, when the result is certifiable — wipe_status absent or completed, and validation absent or approved — AVERASE enqueues certificate generation (a signed PDF uploaded to private storage) and fires the wipe_session_completed webhook. Non-certifiable results are persisted and listed on /webapp/wipes but never certify.

Request body

Responses

• 201 — first receipt; certificate generation enqueued when certifiable.
• 200 — duplicate job_id; the existing record, no side effects.
• 403 — token not active.
• 404 — {"error": "unknown token"}.
• 422 — {"error": "missing job_id"}.

certificate_status in the response is the current state of the certificate pipeline (pending, generating, complete, failed) — don't poll it; the certificate_generated webhook announces completion.

Saves the hotswap station's bay map — the mapping-wizard output that ties physical bay labels to controller lanes — keyed to the chassis by its DMI identity (system.uuid + system.serial). The endpoint first records the chassis itself as an asset (so the chassis appears in /webapp/inventory), then stores the map.

Bay normalization

Each entry in map.bays must have a non-blank lane and label; entries missing either are dropped. An optional connector is kept only when it is an object. If normalization leaves no usable bays, the request fails with 422.

Request body

Responses

• 201 — map saved (and chassis asset upserted).
• 403 / 404 — as elsewhere.
• 422 — {"error": "missing record_id or fingerprint"} or {"error": "map has no usable bays"}.

Fetches a previously saved bay map by chassis DMI identity — the hotswap station calls this at every boot so bay labels survive re-imaging. It is a read modelled as a POST because the HMAC scheme signs the request body.

Request body

Responses

Always 200: {"found": true, "map": {...}} when a map exists for this account and chassis, {"found": false} otherwise — a station booting an unmapped chassis simply runs the mapping wizard.