Documentation

Device & API reference

1. Pair a device

In Devices, click New device and copy the one-time provisioning token.
On the Pi / Jetson, set SWRM_PROV_TOKEN and run the pairing script.
The device receives a persistent swrm_dk_… API key. Store it in /etc/swrm/token.

2. Ingest reference

All endpoints require Authorization: Bearer swrm_dk_….

Method	Path	Purpose
POST	/api/public/v1/pair	Exchange a one-time provisioning token for a persistent device API key.
POST	/api/public/v1/enroll	Fleet self-registration via an enrollment code (Raspberry Pi / Jetson factory flows).
GET	/api/public/v1/config	Bootstrap config: identity, location, active model, sensor keys, endpoints.
GET	/api/public/v1/sensor-types	Public list of registered sensor types (keys + units).
POST	/api/public/v1/heartbeat	Report device liveness, firmware version, uptime, IP.
POST	/api/public/v1/telemetry	Push arbitrary telemetry key/value pairs.
POST	/api/public/v1/sensors	Push sensor readings; triggers alert evaluation.
POST	/api/public/v1/events	Report device events (errors, boots, model swaps).
POST	/api/public/v1/captures	Upload an image + detection results; auto-snapshots recent sensor readings.
POST	/api/public/v1/labels	Attach or replace detections on an existing capture (async inference).
GET	/api/public/v1/model	Fetch active model deployment + short-lived signed download URL.
GET	/api/public/v1/commands	Long-poll the command queue for reboot / model deploy commands.
POST	/api/public/v1/commands/:id/ack	Acknowledge a queued command.

3. Python client

Drop-in snippet for Raspberry Pi and Jetson.

import os, time, requests
API = "https://your-swrm-host"
TOKEN = os.environ["SWRM_TOKEN"]  # swrm_dk_...
H = {"Authorization": f"Bearer {TOKEN}"}

# Heartbeat every 30s
requests.post(f"{API}/api/public/v1/heartbeat", headers=H,
              json={"firmware_version": "1.0.0", "uptime_seconds": 42})

# Sensor reading
requests.post(f"{API}/api/public/v1/sensors", headers=H,
              json={"readings": [{"sensor_type": "temperature", "value": 23.4, "unit": "C"}]})

# Capture with detections
with open("frame.jpg", "rb") as f:
    requests.post(f"{API}/api/public/v1/captures", headers=H,
                  files={"image": ("frame.jpg", f, "image/jpeg")},
                  data={"meta": '{"detections":[{"label":"person","confidence":0.92,"bbox":[10,20,120,240]}]}'})

4. Security

Tokens are SHA-256 hashed at rest — revoke and rotate any time from Settings → API Keys.
All ingest routes are rate-limited and logged with source IP.
Row-level security scopes every read to organization membership.