Files
FireworksApp/SENSOR_SUBMISSION_API.md
2026-10-10 16:03:14 +02:00

2.0 KiB
Raw Permalink Blame History

Sensor submission contract (v1)

POST /api/pending/ accepts multipart/form-data from an active, registered sensor. Send Authorization: Bearer <sensor token>. The token determines the sensor and owner; send the sensor's database ID in sensor_id as an assertion, never as authority.

Required parts: file (16-bit PCM mono WAV), sensor_id, event_id (1–100 ASCII letters, digits, _ or -), captured_at (UTC ISO 8601 timestamp with offset or Unix seconds, or omit it with time_state=unknown when the device clock was not synchronized), duration_seconds (positive number matching the WAV within 0.1 seconds), and firmware_version (1–64 printable characters). Optional: trigger_type (short label), signal_rms, signal_peak (finite nonnegative numbers), and latitude/longitude (untrusted device claims, retained only as metadata). No client location is promoted to the trusted event location.

WAV data must be PCM, mono, 16-bit, at 16 kHz, at most 25 MiB, and 0.1–30 seconds long. A successful first submission returns HTTP 201 with event_id, submission_id, status: pending, and classifier results. A repeat of the same (sensor, event_id) returns HTTP 200 with the same event_id, submission_id, and duplicate: true; a different body with the same ID returns HTTP 409. Errors have code and detail fields. HTTP 429 means retry after the Retry-After interval. HTTP 502 means classification failed and the device should retain the queued clip.

The existing /fireworks/classify/ route remains available for older clients. New firmware should use this contract. Pending audio stays behind the staff-only playback route and follows the existing accept/reject workflow and storage lifetime.

captured_at means the start of the actual recorded WAV. Optional capture_started_at, triggered_at, and queued_at are UTC ISO 8601 timestamps; time_state=unknown leaves the database capture time null. A missing timestamp without that explicit state is invalid.