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

12 lines
2.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.