1.2 KiB
BoomCast sensor upload contract
See ../../../django/SENSOR_SUBMISSION_API.md for the authoritative backend contract. The firmware sends HTTPS POST /api/pending/ with Authorization: Bearer <sensor token> and multipart fields sensor_id, stable filename-derived event_id, duration_seconds, firmware_version, trigger_type, and file (16 kHz, mono, signed 16-bit PCM WAV). It sends UTC ISO 8601 captured_at for the start of the actual WAV, plus optional capture_started_at, triggered_at, and queued_at. Without a synchronized clock it sends time_state=unknown, and the server stores a null capture time.
HTTP 201 is the first durable Pending Review submission. HTTP 200 with duplicate: true acknowledges an existing submission. Both must return the exact event_id, a 36-character submission_id, and status of pending or reviewed; the firmware retains the WAV on any missing, malformed, or mismatched receipt. HTTP 401/403/409 and most other 4xx indicate configuration or validation failures and trigger a slow retry; 408/429, 5xx, timeouts, and TLS errors retry with bounded exponential backoff. The sensor token determines identity and owner, and an untrusted device location never becomes a trusted location.