Files
FireworksApp/SENSOR_SUBMISSION_API.md
T

1.6 KiB
Raw 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), 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 submission_id, status: pending, and classifier results. A repeat of the same (sensor, event_id) returns HTTP 200 with the same 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.