Skip to main content

​
Authentication

All API requests require an API key passed via the X-API-Key header. 
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices
Keep your API key secret. Never expose it in client-side code or commit it to git.

​
Device identifiers

Always use hardware_id when querying or filtering devices.

​
1. Check the API is running

The health endpoint requires no authentication: 
curl https://your-api-host/health

{
	"status": "ok",
	"timestamp": "2025-12-17T10:30:00.000Z"
}

​
2. List your devices

Fetch the devices your API key has access to: 
curl -H "X-API-Key: YOUR_API_KEY" https://your-api-host/devices

{
	"devices": [
		{
			"short_id": "a1b2c3d4",
			"hardware_id": "ABC123",
			"device_type": "teebox",
			"name": "",
			"is_online": true,
			"attributes": {
				"lat": 37.7749,
				"long": -122.4194,
				"battery_voltage": 12.4,
				"lock_status": false
			}
		}
	],
	"pagination": { "limit": 100, "offset": 0, "returned": 1 }
}
Results are automatically scoped to devices within your access. Admin users see all devices.
The attributes object contains the device’s latest telemetry state — GPS coordinates, battery, lock status, and other data are all nested here.

​
3. Filter devices

Fetch specific devices by passing hardware_ids: 
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-api-host/devices?hardware_ids=ABC123,DEF456"

​
4. Subscribe to realtime updates

Connect via WebSocket and subscribe to devices by hardware ID: 
const ws = new WebSocket("wss://your-api-host/realtime?api_key=YOUR_API_KEY");

ws.onopen = () => {
	ws.send(
		JSON.stringify({
			type: "subscribe",
			hardwareIds: ["ABC123"],
		}),
	);
};

ws.onmessage = (event) => {
	const msg = JSON.parse(event.data);
	if (msg.type === "device_data") {
		console.log("Telemetry:", msg.hardwareId, msg.payload);
	}
};

​
5. Receive device data

Each device_data message contains only the fields present in that particular update, not the full device state. 
{
	"type": "device_data",
	"hardwareId": "ABC123",
	"payload": {
		"lat": 37.7749,
		"long": -122.4194,
		"speed": 15.5,
		"battery_voltage": 12.4
	},
	"timestamp": "2025-12-17T10:30:00.000Z",
	"updated_at": "2025-12-17T10:30:00.000Z",
	"last_responded_at": "2025-12-17T10:30:00.000Z"
}
A device may send only GPS fields in one update and only battery data in the next. Always check for the presence of fields before using them.

​
What’s next

Devices

Browse and query your IoT device fleet.

Telemetry

Query GPS and battery history for any device.

Trips

Compute trips and stops from GPS telemetry.

WebSocket

Full WebSocket reference for realtime subscriptions.